@economic/agents 2.13.0 → 2.14.0

package/README.md

@@ -421,6 +421,7 @@ import { z } from "zod";
 
 export const weatherSkill = skill({
   name: "weather",
+  command: "weather",
   description: "Look up current weather and forecasts. Use for any weather question.",
   instructions: `
 # Weather
@@ -445,6 +446,16 @@ Use this skill whenever the user asks about current conditions or a forecast.
 
 Return skills from `getSkills()`. Add `authorize(ctx)` to gate a skill (and its tools). Denied skills are hidden from the catalog and `activate_skill` by default. Set `onUnauthorized` to a reason string, or a function that returns one, to expose a denied skill with user-facing guidance. A function can return `undefined` to keep it hidden. `skill()` throws if `description` or `instructions` is missing.
 
+Set `command` to make a code-defined skill directly invocable from chat. For example,
+`/weather in Copenhagen` loads the weather instructions and enables its tools before the
+first model step; the model still interprets `in Copenhagen` and chooses the appropriate
+tool. Commands use lower-case letters, numbers, and hyphens, without the leading `/`.
+
+`ChatAgent` also exposes an authenticated `GET getInvocableSkills` action for command
+pickers. It returns the commands available to the current user as
+`{ command, name, description }[]`. The existing skill `description` is used for both the
+model catalog and the human-facing picker.
+
 ### Native Agent Skills
 
 Native Agent Skills are folders containing a `SKILL.md` file, with optional references and scripts:

package/dist/index.d.mts

@@ -153,6 +153,11 @@ type AnalyticsEventPayload = {
   durationMs: number;
   inputSize: number;
   outputSize: number;
+} | {
+  type: "skill.invoked";
+  skillName: string;
+  command: string;
+  source: "slash-command";
 } | {
   type: "feedback.submitted";
   messageId: string;
@@ -207,6 +212,7 @@ declare class Analytics {
   promptReceived(messages: readonly ModelMessage[], continuation: boolean): void;
   turnCompleted(requestId: string, status: string, continuation: boolean, response: unknown): void;
   feedbackSubmitted(messageId: string, rating: 1 | -1 | 0): void;
+  skillInvoked(skillName: string, command: string): void;
   event(payload: AnalyticsEventPayload | (() => AnalyticsEventPayload)): void;
 }
 //#endregion
@@ -432,12 +438,69 @@ type MessageFeedback = {
   updated_at: number;
 };
 //#endregion
+//#region src/server/util/actions.d.ts
+/** Tool execution options plus the additional context supplied by native Think actions. */
+type ActionContext<Context extends Record<string, unknown> = Record<string, unknown>> = Omit<ToolExecutionOptions, "experimental_context"> & ActionContext$1 & {
+  experimental_context: Context; /** The action's resolved domain key, or its tool-call fallback when none was declared. */
+  idempotencyKey: string;
+};
+type Action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any> = Omit<ActionConfig<FlexibleSchema<Input>, Output>, "approval" | "execute" | "idempotencyKey" | "inputSchema" | "permissions"> & {
+  description: string;
+  inputSchema: FlexibleSchema<Input>;
+  approval?: ActionApprovalPolicy<Input>;
+  idempotencyKey?: ActionIdempotencyKey<Input>;
+  permissions?: ActionPermissionSpec<Input>;
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+  execute(input: Input, ctx: ActionContext<Context>): Promise<Output> | Output;
+};
+type RegisteredAction<Context extends Record<string, unknown> = Record<string, unknown>, InputSchema extends FlexibleSchema = FlexibleSchema, Output = unknown> = Action$1<InputSchema, Output> & {
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+};
+/** A native Think action with the SDK's standard authorization policy. */
+declare function action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any>(definition: Action<Context, Input, Output>): RegisteredAction<Context, FlexibleSchema<Input>, Output>;
+//#endregion
+//#region src/server/util/skills.d.ts
+interface Skill<Context extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  description: string;
+  instructions: string;
+  /** Enables direct invocation from chat with `/command`. */
+  command?: string;
+  tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, RegisteredAction<Context, any, any>>;
+  authorize?: (ctx?: Context) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+}
+interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
+  command?: string;
+  tools?: Record<string, Tool<Context>>;
+  actions?: Record<string, RegisteredAction<Context, any, any>>;
+  authorize?: (ctx?: Context | undefined) => boolean;
+  onUnauthorized?: UnauthorizedPolicy<Context>;
+}
+declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
+//#endregion
+//#region src/server/util/skillCommands.d.ts
+interface InvocableSkill {
+  /** Slash command without the leading `/`. */
+  command: string;
+  /** Name of the skill the command activates. */
+  name: string;
+  /** Human- and model-readable summary from the skill definition. */
+  description: string;
+}
+//#endregion
 //#region src/server/agents/ChatAgent.d.ts
 declare abstract class ChatAgent<RequestContext extends Record<string, unknown> = Record<string, unknown>, UserContext extends Record<string, unknown> = Record<string, unknown>, State = unknown> extends Agent<RequestContext, UserContext, State> {
   protected agentType: AgentConnectionType;
   onStart(): Promise<void>;
   configureSession(session: Session): Session;
   beforeTurn(ctx: TurnContext): Promise<void | TurnConfig>;
+  private getSlashCommandSkill;
+  private invokeSkill;
+  protected getInvocableSkills(userContext?: UserContext | undefined, requestContext?: RequestContext): Promise<InvocableSkill[]>;
   onChatResponse(result: ChatResponseResult): Promise<void>;
   onRequest(request: Request): Promise<Response>;
   /**
@@ -512,51 +575,10 @@ declare abstract class Assistant<State = unknown> extends Agent$1<Cloudflare.Env
   observability?: Observability;
 }
 //#endregion
-//#region src/server/util/actions.d.ts
-/** Tool execution options plus the additional context supplied by native Think actions. */
-type ActionContext<Context extends Record<string, unknown> = Record<string, unknown>> = Omit<ToolExecutionOptions, "experimental_context"> & ActionContext$1 & {
-  experimental_context: Context; /** The action's resolved domain key, or its tool-call fallback when none was declared. */
-  idempotencyKey: string;
-};
-type Action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any> = Omit<ActionConfig<FlexibleSchema<Input>, Output>, "approval" | "execute" | "idempotencyKey" | "inputSchema" | "permissions"> & {
-  description: string;
-  inputSchema: FlexibleSchema<Input>;
-  approval?: ActionApprovalPolicy<Input>;
-  idempotencyKey?: ActionIdempotencyKey<Input>;
-  permissions?: ActionPermissionSpec<Input>;
-  authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-  execute(input: Input, ctx: ActionContext<Context>): Promise<Output> | Output;
-};
-type RegisteredAction<Context extends Record<string, unknown> = Record<string, unknown>, InputSchema extends FlexibleSchema = FlexibleSchema, Output = unknown> = Action$1<InputSchema, Output> & {
-  authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-};
-/** A native Think action with the SDK's standard authorization policy. */
-declare function action<Context extends Record<string, unknown> = Record<string, unknown>, Input = any, Output = any>(definition: Action<Context, Input, Output>): RegisteredAction<Context, FlexibleSchema<Input>, Output>;
-//#endregion
-//#region src/server/util/skills.d.ts
-interface Skill<Context extends Record<string, unknown> = Record<string, unknown>> {
-  name: string;
-  description: string;
-  instructions: string;
-  tools?: Record<string, Tool<Context>>;
-  actions?: Record<string, RegisteredAction<Context, any, any>>;
-  authorize?: (ctx?: Context) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-}
-interface SkillSource<Context extends Record<string, unknown> = Record<string, unknown>> extends SkillSource$1 {
-  tools?: Record<string, Tool<Context>>;
-  actions?: Record<string, RegisteredAction<Context, any, any>>;
-  authorize?: (ctx?: Context | undefined) => boolean;
-  onUnauthorized?: UnauthorizedPolicy<Context>;
-}
-declare function skill<Context extends Record<string, unknown> = Record<string, unknown>>(definition: Skill<Context>): SkillSource<Context>;
-//#endregion
 //#region src/server/route-agent-request.d.ts
 declare function routeAgentRequest<Env>(request: Request, env: Env, options?: AgentOptions<Env>): Promise<Response | null>;
 //#endregion
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type AnalyticsAttribute, type AnalyticsAttributes, type AnalyticsEvent, type AnalyticsEventPayload, type AnalyticsHandler, type AnalyticsUsage, Assistant, ChatAgent, type ExchangedToken, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };
+export { type Action, type ActionContext, Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, type AnalyticsAttribute, type AnalyticsAttributes, type AnalyticsEvent, type AnalyticsEventPayload, type AnalyticsHandler, type AnalyticsUsage, Assistant, ChatAgent, type ExchangedToken, type InvocableSkill, type JwtAuthConfig, type RegisteredAction, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, type UnauthorizedPolicy, type UnauthorizedToolPolicy, action, createAnalyticsEngineHandler, createAnalyticsEvent, createJwtAuthConfig, dispatchAnalyticsEvent, exchangeToken, getCurrentToolContext, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -905,6 +905,19 @@ function toAnalyticsEnginePoints(event) {
 				0
 			]
 		}));
+		case "skill.invoked": return [{
+			indexes,
+			blobs: [
+				"skill_invoked",
+				event.agentName,
+				event.durableObjectName,
+				event.skillName,
+				event.command,
+				event.source,
+				...common
+			],
+			doubles: [1]
+		}];
 		case "feedback.submitted": return [{
 			indexes,
 			blobs: [
@@ -998,6 +1011,14 @@ var Analytics = class {
 			rating
 		});
 	}
+	skillInvoked(skillName, command) {
+		this.emit({
+			type: "skill.invoked",
+			skillName,
+			command,
+			source: "slash-command"
+		});
+	}
 	event(payload) {
 		this.emit(payload);
 	}
@@ -1161,7 +1182,6 @@ var Agent = class extends Think {
 		const { tools, activeTools } = await this._prepareTools(ctx.tools, activeSkillName, true);
 		const baseSystem = await this.session.refreshSystemPrompt();
 		this._turn.baseSystem = [baseSystem, this._turn.skillsSystemBlock].filter(Boolean).join("\n\n");
-		console.log(this._turn.baseSystem, "\n\n// end system prompt\n\n");
 		return {
 			system: this._turn.baseSystem,
 			model: this.getModel(this._turn.context),
@@ -2338,6 +2358,38 @@ var Assistant = class extends Agent$1 {
 		agentClass: this.constructor.name
 	}) });
 };
+//#endregion
+//#region src/server/util/skillCommands.ts
+async function listInvocableSkills(sources) {
+	const commands = /* @__PURE__ */ new Set();
+	const skills = [];
+	for (const source of sources) {
+		if (!source.command) continue;
+		if (commands.has(source.command)) throw new Error(`Duplicate skill command "/${source.command}"`);
+		const descriptor = (await source.list()).find((skill) => skill.name === source.id);
+		if (!descriptor) continue;
+		commands.add(source.command);
+		skills.push({
+			command: source.command,
+			name: descriptor.name,
+			description: descriptor.description
+		});
+	}
+	return skills;
+}
+function parseSkillCommand(messages, skills) {
+	const message = messages.findLast((candidate) => candidate.role === "user");
+	if (!message) return;
+	const text = getMessageText(message);
+	if (!text?.startsWith("/")) return;
+	const match = /^\/([^\s]+)/.exec(text);
+	if (!match) return;
+	return skills.find((skill) => skill.command === match[1]);
+}
+function getMessageText(message) {
+	if (typeof message.content === "string") return message.content;
+	return message.content.filter((part) => part.type === "text").map((part) => part.text).join("") || void 0;
+}
 const COMPACTION_MAX_OUTPUT_TOKENS = 2e3;
 const createCompactFn = (model) => createCompactFunction({
 	protectHead: 2,
@@ -2675,7 +2727,22 @@ var ChatAgent = class extends Agent {
 	async beforeTurn(ctx) {
 		const parent = await this.getParentAgent();
 		if (parent?.registerChat) await parent.registerChat(this.name);
-		const config = await super.beforeTurn(ctx) ?? {};
+		const slashCommandSkill = await this.getSlashCommandSkill(ctx);
+		let skillInvocation;
+		if (slashCommandSkill) skillInvocation = await this.invokeSkill(ctx, slashCommandSkill);
+		const turnContext = skillInvocation ? {
+			...ctx,
+			messages: [...ctx.messages, ...skillInvocation.messages]
+		} : ctx;
+		let config = await super.beforeTurn(turnContext) ?? {};
+		if (skillInvocation) {
+			const transforms = config.experimental_transform ? Array.isArray(config.experimental_transform) ? config.experimental_transform : [config.experimental_transform] : [];
+			config = {
+				...config,
+				activeTools: config.activeTools?.filter((name) => name !== "activate_skill"),
+				experimental_transform: [skillInvocation.transform, ...transforms]
+			};
+		}
 		try {
 			const prepared = await prepareModelHistory(this.messages, getModelCompaction(this.sql.bind(this)), createCompactFn(config.model ?? ctx.model), config.system ?? ctx.system);
 			if (prepared.stateChanged) if (prepared.state) setModelCompaction(this.sql.bind(this), prepared.state);
@@ -2691,7 +2758,7 @@ var ChatAgent = class extends Agent {
 				});
 				return {
 					...config,
-					messages: this.pruneTurnMessages(modelMessages)
+					messages: this.pruneTurnMessages([...modelMessages, ...skillInvocation?.messages ?? []])
 				};
 			}
 		} catch (error) {
@@ -2699,6 +2766,67 @@ var ChatAgent = class extends Agent {
 		}
 		return config;
 	}
+	async getSlashCommandSkill(context) {
+		if (context.continuation) return;
+		const connectionState = getCurrentAgent()?.connection?.state;
+		const invocableSkills = await this.getInvocableSkills(connectionState?.userContext ?? this.userContext, context.body);
+		return parseSkillCommand(context.messages, invocableSkills);
+	}
+	async invokeSkill(context, skill) {
+		const activateSkill = context.tools.activate_skill;
+		if (!activateSkill?.execute) return;
+		const input = { name: skill.name };
+		const toolCallId = crypto.randomUUID();
+		const output = await activateSkill.execute(input, {
+			toolCallId,
+			messages: context.messages
+		});
+		if (typeof output !== "string") throw new Error("activate_skill returned an invalid result");
+		this.analytics.skillInvoked(skill.name, skill.command);
+		const messages = await convertToModelMessages([{
+			id: crypto.randomUUID(),
+			role: "assistant",
+			parts: [{
+				type: "tool-activate_skill",
+				toolCallId,
+				state: "output-available",
+				input,
+				output
+			}]
+		}], { tools: context.tools });
+		const transform = () => {
+			let emitted = false;
+			return new TransformStream({ transform(chunk, controller) {
+				controller.enqueue(chunk);
+				if (emitted || chunk.type !== "start-step") return;
+				emitted = true;
+				controller.enqueue({
+					type: "tool-call",
+					toolCallId,
+					toolName: "activate_skill",
+					input
+				});
+				controller.enqueue({
+					type: "tool-result",
+					toolCallId,
+					toolName: "activate_skill",
+					input,
+					output
+				});
+			} });
+		};
+		return {
+			messages,
+			transform
+		};
+	}
+	async getInvocableSkills(userContext = this.userContext, requestContext = {}) {
+		const context = {
+			...requestContext,
+			_userContext: userContext
+		};
+		return listInvocableSkills((await this.getSkills()).filter((source) => source.authorize?.(context) !== false));
+	}
 	async onChatResponse(result) {
 		this.analytics.turnCompleted(result.requestId, result.status, result.continuation, result.message.parts);
 		const parent = await this.getParentAgent();
@@ -2709,6 +2837,7 @@ var ChatAgent = class extends Agent {
 		if (!auth.success) return Response.json({ error: auth.message }, { status: auth.status });
 		const action = new URL(request.url).pathname.split("/").pop();
 		if (action === "getMessages" && request.method === "GET") return Response.json(await this.getMessages());
+		if (action === "getInvocableSkills" && request.method === "GET") return Response.json(await this.getInvocableSkills(auth.userContext));
 		if (action === "sendMessage" && request.method === "POST") return this.streamMessage(request);
 		if (action === "cancelChat" && request.method === "POST") {
 			const { requestId } = await request.json();
@@ -2828,6 +2957,7 @@ function skill(definition) {
 	if (!definition.name) throw new Error("Skill name is required");
 	if (!definition.description) throw new Error("Skill description is required");
 	if (!definition.instructions) throw new Error("Skill content is required");
+	if (definition.command !== void 0 && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(definition.command)) throw new Error("Skill command must use lower-case letters, numbers, and hyphens");
 	return {
 		id: definition.name,
 		fingerprint: definition.name,
@@ -2845,6 +2975,7 @@ function skill(definition) {
 				body: definition.instructions
 			};
 		},
+		command: definition.command,
 		tools: definition.tools,
 		actions: definition.actions,
 		authorize: definition.authorize,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@cloudflare/think": "^0.17.0",
-    "@cloudflare/vite-plugin": "^1.43.0 <1.43.2",
+    "@cloudflare/vite-plugin": "^1.45.1",
     "@cloudflare/worker-bundler": "^0.2.1",
     "agents": "^0.22.0",
     "vite": ">=8.0.0"