@economic/agents 0.0.1-alpha.4 → 0.0.1-alpha.6

package/dist/index.d.mts

@@ -105,6 +105,14 @@ interface SkillsConfig {
   tools: ToolSet;
   /** All available skills that can be loaded on demand */
   skills: Skill[];
+  /**
+   * The base system prompt for the agent. When provided, createSkills uses
+   * this to compose the full system string (base + guidance) returned by
+   * getSystem() and from prepareStep. Guidance is kept in the system
+   * parameter rather than the messages array — Anthropic/Gemini only allow
+   * system messages at the start of the conversation.
+   */
+  systemPrompt?: string;
   /**
    * Skill names that were loaded in previous turns, read from D1 at turn
    * start. Seeds the in-memory loadedSkills set so prior state is restored
@@ -128,16 +136,17 @@ interface SkillsConfig {
 /**
  * Skill context injected by the @withSkills decorator.
  *
- * Spread the context fields directly into streamText — messages already has
- * guidance injected at the correct position:
+ * Spread the skill fields into streamText and pass headers via
+ * experimental_context so tools can read them from their second execute arg:
  *
  * ```typescript
- * const { messages, ...skillArgs } = ctx;
+ * const { messages, headers, guidance, ...skillArgs } = ctx;
  * return streamText({
  *   model: this.getModel(),
  *   system: "Your base prompt — static, never includes guidance",
  *   messages,
  *   ...skillArgs,
+ *   experimental_context: { headers },
  *   onFinish,
  *   stopWhen: stepCountIs(20),
  * }).toUIMessageStreamResponse();
@@ -149,16 +158,25 @@ interface SkillContext {
   /** Currently active tool names — spread into streamText */
   activeTools: string[];
   /**
-   * Updates active tools and the guidance system message before each LLM step.
-   * Spread into streamText.
+   * Updates activeTools before each LLM step. Spread into streamText.
    */
   prepareStep: ai.PrepareStepFunction;
   /**
-   * Conversation messages read from D1 with current skill guidance already
-   * injected just before the last message (the current user turn). Pass
-   * directly as the `messages` param of streamText.
+   * Guidance text from all currently-loaded skills. Compose your system
+   * prompt as: `${myBase}${guidance ? '\n\n' + guidance : ''}`
+   */
+  guidance: string;
+  /**
+   * Plain conversation history from DO SQLite — no guidance injected.
+   * Pass directly as the `messages` param of streamText.
    */
   messages: ai.ModelMessage[];
+  /**
+   * Headers captured from the WebSocket upgrade request, filtered to the
+   * names returned by getTrackedHeaders(). Pass to tools via
+   * experimental_context: `streamText({ experimental_context: { headers }, ... })`
+   */
+  headers: Record<string, string>;
 }
 /**
  * The object returned by createSkills().
@@ -169,6 +187,12 @@ interface SkillsResult {
   getLoadedGuidance(): string;
   /** Current loaded skill names */
   getLoadedSkills(): string[];
+  /**
+   * Full system string: base system prompt concatenated with guidance from
+   * all currently-loaded skills. Only meaningful when `systemPrompt` was
+   * passed to createSkills. Use as the `system` param of streamText.
+   */
+  getSystem(): string;
 }
 //#endregion
 //#region src/agents/chat/AIChatAgentBase.d.ts
@@ -227,6 +251,21 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
    * tail is maxPersistedMessages - 1 recent messages. Raise or lower per agent.
    */
   maxPersistedMessages: number;
+  /**
+   * Query parameter names to read from the WebSocket connection URL and
+   * forward to tools via experimental_context.
+   *
+   * Browsers cannot set custom headers on WebSocket upgrade requests, so
+   * auth tokens and other metadata must be passed as query parameters instead.
+   *
+   * ```typescript
+   * passthroughRequestHeaders = ['authorization', 'x-user-id'];
+   * ```
+   *
+   * Values are read from the URL at connect time and stored in _requestHeaders
+   * for the lifetime of the Durable Object instance.
+   */
+  passthroughRequestHeaders: string[];
   /** Tools that are always active regardless of loaded skills */
   abstract getTools(): ToolSet;
   /** All skills available for on-demand loading */
@@ -259,6 +298,8 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
    * skill when activate_skill is called. Defaults to allow-all.
    */
   protected filterSkill(_skillName: string): Promise<boolean>;
+  /** @internal Captured header values, keyed by lowercase name. */
+  protected _requestHeaders: Record<string, string>;
   /**
    * Buffered skill state from the current turn.
    *
@@ -331,13 +372,14 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
   /**
    * Called by the @withSkills decorator at the start of each turn.
    *
-   * Reads loaded skill state from D1, seeds createSkills, injects guidance,
-   * and returns a SkillContext ready to use in a streamText call.
+   * Reads loaded skill state from D1, seeds createSkills, and returns a
+   * SkillContext ready to use in a streamText call.
    *
-   * The returned `messages` already has guidance injected just before the
-   * current user turn — pass it directly as the `messages` param of streamText.
-   * Guidance is never stored in DO SQLite, so loaded_skills in D1 is the
-   * single source of truth for which skills are active.
+   * Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+   * `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
+   *
+   * Messages are plain (no guidance injected). Guidance stays out of the
+   * messages array — Anthropic/Gemini only allow system messages at position 0.
    */
   protected _prepareSkillContext(): Promise<SkillContext>;
 }
@@ -358,10 +400,11 @@ declare abstract class AIChatAgentBase<Env extends Cloudflare.Env = Cloudflare.E
  *   ctx: SkillContext,
  *   options?: OnChatMessageOptions,
  * ) {
- *   const { messages, ...skillArgs } = ctx;
+ *   const { messages, guidance, ...skillArgs } = ctx;
+ *   const base = "Your base prompt";
  *   return streamText({
  *     model: this.getModel(),
- *     system: "Your base prompt — static, never includes guidance",
+ *     system: guidance ? `${base}\n\n${guidance}` : base,
  *     messages,
  *     ...skillArgs,
  *     onFinish,
@@ -390,13 +433,30 @@ declare function withSkills(fn: WithSkillsFn, _context: ClassMethodDecoratorCont
  * ```typescript
  * export class MyAgent extends AIChatAgent {
  *   getModel()        { return openai("gpt-4o"); }
- *   getTools()        { return []; }
+ *   getTools()        { return tools; }
  *   getSkills()       { return [searchSkill, codeSkill]; }
  *   getSystemPrompt() { return "You are a helpful assistant."; }
  *   getDB()           { return this.env.AGENT_DB; }
  * }
  * ```
  *
+ * ## Passing auth headers to tools
+ *
+ * Set `passthroughRequestHeaders` to capture headers from the WebSocket upgrade
+ * request. They are forwarded automatically to every tool via `experimental_context`:
+ *
+ * ```typescript
+ * passthroughRequestHeaders = ['authorization', 'x-user-id'];
+ * ```
+ *
+ * Tools receive them as the second `execute` argument:
+ *
+ * ```typescript
+ * execute: async (args, { experimental_context }) => {
+ *   const { authorization } = experimental_context?.headers ?? {};
+ * }
+ * ```
+ *
  * If you need full control over the `streamText` call (custom model options,
  * streaming transforms, varying the model per request, etc.) use
  * `AIChatAgentBase` with the `@withSkills` decorator instead.

package/dist/index.mjs

@@ -80,7 +80,11 @@ function createSkills(config) {
 	function getLoadedGuidance() {
 		return [...loadedSkills].map((name) => skillMap.get(name)?.guidance).filter((g) => Boolean(g)).join("\n\n");
 	}
-	let previousGuidance = getLoadedGuidance();
+	function getSystem() {
+		const guidance = getLoadedGuidance();
+		if (!config.systemPrompt) return guidance;
+		return guidance ? `${config.systemPrompt}\n\n${guidance}` : config.systemPrompt;
+	}
 	allTools[ACTIVATE_SKILL] = tool({
 		description: buildActivateSkillDescription(skills),
 		inputSchema: jsonSchema({
@@ -136,13 +140,10 @@ function createSkills(config) {
 			].join("\n");
 		}
 	});
-	const prepareStep = async ({ messages }) => {
-		const guidance = getLoadedGuidance();
-		const updatedMessages = injectGuidance(messages, guidance, previousGuidance);
-		previousGuidance = guidance;
+	const prepareStep = async () => {
 		return {
 			activeTools: getActiveToolNames(),
-			messages: updatedMessages
+			...config.systemPrompt !== void 0 && { system: getSystem() }
 		};
 	};
 	return {
@@ -150,6 +151,7 @@ function createSkills(config) {
 		activeTools: getActiveToolNames(),
 		prepareStep,
 		getLoadedGuidance,
+		getSystem,
 		getLoadedSkills() {
 			return [...loadedSkills];
 		}
@@ -237,13 +239,14 @@ function filterEphemeralMessages(messages, guidanceToStrip) {
 function injectGuidance(messages, guidance, previousGuidance) {
 	if (!guidance) return messages;
 	const base = previousGuidance ? messages.filter((m) => !(m.role === "system" && m.content === previousGuidance)) : messages;
+	const insertAt = base.findLastIndex((m) => m.role === "user");
 	return [
-		...base.slice(0, -1),
+		...base.slice(0, insertAt),
 		{
 			role: "system",
 			content: guidance
 		},
-		base.at(-1)
+		...base.slice(insertAt)
 	];
 }
 //#endregion
@@ -444,6 +447,21 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	*/
 	maxPersistedMessages = 50;
 	/**
+	* Query parameter names to read from the WebSocket connection URL and
+	* forward to tools via experimental_context.
+	*
+	* Browsers cannot set custom headers on WebSocket upgrade requests, so
+	* auth tokens and other metadata must be passed as query parameters instead.
+	*
+	* ```typescript
+	* passthroughRequestHeaders = ['authorization', 'x-user-id'];
+	* ```
+	*
+	* Values are read from the URL at connect time and stored in _requestHeaders
+	* for the lifetime of the Durable Object instance.
+	*/
+	passthroughRequestHeaders = [];
+	/**
 	* Return a LanguageModel to use for compaction summarisation.
 	*
 	* Return undefined (default) to disable compaction — messages are kept up
@@ -473,6 +491,8 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	async filterSkill(_skillName) {
 		return true;
 	}
+	/** @internal Captured header values, keyed by lowercase name. */
+	_requestHeaders = {};
 	/**
 	* Buffered skill state from the current turn.
 	*
@@ -516,6 +536,14 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	* that case and replays in-progress chunks via its own protocol.
 	*/
 	async onConnect(connection, ctx) {
+		if (this.passthroughRequestHeaders.length > 0) {
+			this._requestHeaders = {};
+			const params = new URL(ctx.request.url).searchParams;
+			for (const name of this.passthroughRequestHeaders) {
+				const value = params.get(name);
+				if (value !== null) this._requestHeaders[name] = value;
+			}
+		}
 		await super.onConnect(connection, ctx);
 		if (!this._activeStreamId && this.messages.length > 0) connection.send(JSON.stringify({
 			type: "cf_agent_chat_messages",
@@ -565,13 +593,14 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 	/**
 	* Called by the @withSkills decorator at the start of each turn.
 	*
-	* Reads loaded skill state from D1, seeds createSkills, injects guidance,
-	* and returns a SkillContext ready to use in a streamText call.
+	* Reads loaded skill state from D1, seeds createSkills, and returns a
+	* SkillContext ready to use in a streamText call.
 	*
-	* The returned `messages` already has guidance injected just before the
-	* current user turn — pass it directly as the `messages` param of streamText.
-	* Guidance is never stored in DO SQLite, so loaded_skills in D1 is the
-	* single source of truth for which skills are active.
+	* Guidance is exposed as `ctx.guidance` — compose your system prompt as:
+	* `${myBase}${ctx.guidance ? '\n\n' + ctx.guidance : ''}`
+	*
+	* Messages are plain (no guidance injected). Guidance stays out of the
+	* messages array — Anthropic/Gemini only allow system messages at position 0.
 	*/
 	async _prepareSkillContext() {
 		const loadedSkills = await this._readSkillState();
@@ -584,13 +613,13 @@ var AIChatAgentBase = class extends AIChatAgent$1 {
 			},
 			filterSkill: (name) => this.filterSkill(name)
 		});
-		const guidance = skills.getLoadedGuidance();
-		const messages = injectGuidance(await convertToModelMessages(this.messages), guidance);
 		return {
 			tools: skills.tools,
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,
-			messages
+			guidance: skills.getLoadedGuidance(),
+			messages: await convertToModelMessages(this.messages),
+			headers: this._requestHeaders
 		};
 	}
 };
@@ -619,13 +648,30 @@ function withSkills(fn, _context) {
 * ```typescript
 * export class MyAgent extends AIChatAgent {
 *   getModel()        { return openai("gpt-4o"); }
-*   getTools()        { return []; }
+*   getTools()        { return tools; }
 *   getSkills()       { return [searchSkill, codeSkill]; }
 *   getSystemPrompt() { return "You are a helpful assistant."; }
 *   getDB()           { return this.env.AGENT_DB; }
 * }
 * ```
 *
+* ## Passing auth headers to tools
+*
+* Set `passthroughRequestHeaders` to capture headers from the WebSocket upgrade
+* request. They are forwarded automatically to every tool via `experimental_context`:
+*
+* ```typescript
+* passthroughRequestHeaders = ['authorization', 'x-user-id'];
+* ```
+*
+* Tools receive them as the second `execute` argument:
+*
+* ```typescript
+* execute: async (args, { experimental_context }) => {
+*   const { authorization } = experimental_context?.headers ?? {};
+* }
+* ```
+*
 * If you need full control over the `streamText` call (custom model options,
 * streaming transforms, varying the model per request, etc.) use
 * `AIChatAgentBase` with the `@withSkills` decorator instead.
@@ -648,21 +694,21 @@ var AIChatAgent = class extends AIChatAgentBase {
 		const skills = createSkills({
 			tools: this.getTools(),
 			skills: this.getSkills(),
+			systemPrompt: this.getSystemPrompt(),
 			initialLoadedSkills: loadedSkills,
 			onSkillsChanged: async (updated) => {
 				this._pendingSkills = updated;
 			},
 			filterSkill: (name) => this.filterSkill(name)
 		});
-		const guidance = skills.getLoadedGuidance();
-		const messages = injectGuidance(await convertToModelMessages(this.messages), guidance);
 		return streamText({
 			model: this.getModel(),
-			system: this.getSystemPrompt(),
-			messages,
+			system: skills.getSystem(),
+			messages: await convertToModelMessages(this.messages),
 			tools: skills.tools,
 			activeTools: skills.activeTools,
 			prepareStep: skills.prepareStep,
+			experimental_context: { headers: this._requestHeaders },
 			stopWhen: stepCountIs(20),
 			abortSignal: options?.abortSignal,
 			onFinish

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-alpha.4",
+  "version": "0.0.1-alpha.6",
   "description": "A starter for creating a TypeScript package.",
   "homepage": "https://github.com/author/library#readme",
   "bugs": {