Class: ActionGroupBuilder<TContext, TCommon>

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:103

Type Parameters

Type Parameter	Default type
TContext	-
TCommon extends Record<string, unknown>	Record<string, never>

Constructors

Constructor

new ActionGroupBuilder<TContext, TCommon>(groupName, description?): ActionGroupBuilder<TContext, TCommon>;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:111

Parameters

Parameter	Type
groupName	string
description?	string

Returns

ActionGroupBuilder<TContext, TCommon>

Methods

action()

Call Signature

action<TSchema, TOmit>(config): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:249

Register an action within this group.

As a 2-arg shortcut action(name, handler): registers a standard action (neither read-only nor destructive). This completes the semantic verb trio alongside .query() and .mutation().

As a config object action({ name, schema, ... }): full control over all action properties (schema, description, omitCommon, etc.).

The action key is automatically prefixed with the group name (e.g., action "create" in group "users" becomes "users.create").

Type Parameters

Type Parameter	Default type
TSchema extends ZodObject<ZodRawShape, UnknownKeysParam, ZodTypeAny, { [key: string]: any; }, { [key: string]: any; }>	-
TOmit extends string | number | symbol	never

Parameters

Parameter	Type	Description
config	{ description?: string; destructive?: boolean; handler: (ctx, args) => Promise<ToolResponse>; idempotent?: boolean; name: string; omitCommon?: TOmit[]; readOnly?: boolean; schema: TSchema; }	Action configuration OR action name (string)
config.description?	string	-
config.destructive?	boolean	-
config.handler	(ctx, args) => Promise<ToolResponse>	-
config.idempotent?	boolean	-
config.name	string	-
config.omitCommon?	TOmit[]	-
config.readOnly?	boolean	-
config.schema	TSchema	-

Returns

this

this for chaining

Example

builder.group('users', 'User management', (g) => g
    .query('list', listHandler)
    .action('invite', inviteHandler)
    .mutation('ban', banHandler)
);

See

• ActionGroupBuilder.query — read-only actions
• ActionGroupBuilder.mutation — destructive actions
• ActionConfig for all configuration options

Call Signature

action(name, handler): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:260

Register a standard action (2-arg shorthand: neither readOnly nor destructive)

Parameters

Parameter	Type
name	string
handler	ActionHandler<TContext>

Returns

this

Call Signature

action(config): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:262

Register an action within this group (config object)

Parameters

Parameter	Type
config	ActionConfig<TContext>

Returns

this

---

mutation()

mutation(name, handler): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:213

Register a destructive action (destructive: true).

Semantic shortcut — eliminates the need for config objects. Signals to the LLM that this action has irreversible side effects.

Parameters

Parameter	Type	Description
name	string	Action name (must not contain dots)
handler	ActionHandler<TContext>	Handler function

Returns

this

this for chaining

Example

builder.group('users', 'User management', (g) => g
    .mutation('ban', async (ctx, args) => {
        await ctx.db.users.ban(args.user_id);
        return success('User banned');
    })
);

---

omitCommon()

omitCommon(...fields): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:163

Omit common schema fields for all actions in this group.

Use when an entire group derives common fields from context (e.g. a "profile" group that resolves workspace_id from the JWT).

Per-action omitCommon merges with group-level omissions.

Parameters

Parameter	Type	Description
...fields	string[]	Common field names to omit

Returns

this

this for chaining

Example

builder.group('profile', 'User profile', (g) => g
    .omitCommon('workspace_id')
    .query('me', meHandler)
);

---

query()

query(name, handler): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:189

Register a read-only action (readOnly: true).

Semantic shortcut — eliminates the need for config objects. The action name is automatically prefixed with the group name (e.g., "list" in group "users" → "users.list").

Parameters

Parameter	Type	Description
name	string	Action name (must not contain dots)
handler	ActionHandler<TContext>	Handler function

Returns

this

this for chaining

Example

builder.group('users', 'User management', (g) => g
    .query('list', async (ctx) => success(await ctx.db.users.findMany()))
    .query('get', async (ctx, args) => success(await ctx.db.users.find(args.id)))
);

---

use()

use(mw): this;

Defined in: packages/core/src/core/builder/ActionGroupBuilder.ts:139

Add middleware scoped to this group only.

Unlike GroupedToolBuilder.use, this middleware runs only for actions within this group — not globally.

Accepts both MiddlewareDefinition from f.middleware() and raw MiddlewareFn functions.

Parameters

Parameter	Type	Description
mw	| MiddlewareFn<TContext> | MiddlewareDefinition<TContext, Record<string, unknown>>	Middleware function or MiddlewareDefinition

Returns

this

this for chaining

Example

builder.group('admin', 'Admin operations', (g) => g
    .use(requireAdmin)
    .query('list', listHandler)
    .mutation('reset', resetHandler)
);

See

MiddlewareFn for the middleware signature