@standardagents/agentbuilder-template 0.43.0 → 0.44.0

package/dist/index.js

@@ -42,6 +42,27 @@ the agent relies on it. Authentication, billing, deployment, and branded UI
 services may remain external as long as they are not required for the packed
 agent's core execution semantics.
 
+## Packaging and Definition Visibility
+
+The packer follows side \`subagents\` relationships and includes child agents
+and their dependencies. This includes hidden children and relationships with
+\`as\`. The package includes referenced handlers and exports a \`handlers\`
+registry. The pack and unpack dialogs list handlers. Unpack analysis reports an agent\u2019s handlers and side \`subagents\` relationships.
+In the pack dialog, a handler defaults to extract. Shared handlers default to copy. Extract removes
+the local file; copy keeps it. Dependencies reached by another local agent,
+including through its children, default to copy.
+
+The runtime discovers packages in \`node_modules\` and \`agents/packed/\`.
+It loads definitions from lazy registries and \`__meta\` exported by each
+package entry module. A malformed \`package.json\` or missing or invalid
+\`__meta\` produces a warning and the runtime skips that package.
+
+\`ThreadState.loadModel\`, \`loadPrompt\`, and \`loadAgent\` enforce package
+visibility. Global code can load unpacked definitions and packed entry agents.
+Packed code can load its own definitions and other packages' entry agents.
+A packed model cannot fall back to a host model with the same short name.
+A refused load returns the same not-found error as a missing definition.
+
 ## How Components Compose
 
 ### Basic Flow
@@ -147,7 +168,9 @@ interface ThreadState {
   runtimeStreams?: RuntimeStreams;    // Optional live execution-host byte streams
 
   // Methods
-  getMessages(options?): Promise<MessagesResult>;  // Get conversation history
+  getMessages(options?): Promise<MessagesResult>;  // Get conversation history, newest first by default
+  getMessage(id): Promise<Message | null>;          // Find a persisted message by ID
+  updateMessage(id, updates): Promise<Message>;    // Update a persisted message
   injectMessage(input): Promise<Message>;          // Add message to thread
   queueMessage(input): Promise<void>;              // Queue message for next step
   emit(event, data): void;                         // Broadcast a custom event to connected thread clients
@@ -199,7 +222,7 @@ what was sent (\`request\`), what came back (\`response\` or \`error\`), and its
 execution; oversized fields are truncated (name 120 chars, message and error
 4 KiB, data JSON 16 KiB, request and response JSON 64 KiB each).
 
-\`runCode\` has no implicit access to thread state, filesystem, network, timers, or host globals. Bridge only the exact capabilities needed through \`imports\` or \`globals\`; use \`modules\` for local relative ES modules; use \`execute\` to select the export and args to run. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`filename\` when supplied, including \`../\` parent paths that stay inside the supplied graph. TypeScript input is accepted by default and erased before evaluation. In thread endpoints, \`runCode\` is forwarded into the thread Durable Object; pass plain transferable options there and keep function-backed bridges in tools or in-thread execution contexts.
+\`runCode\` has no implicit access to thread state, filesystem, network, timers, or host globals. Bridge only the exact capabilities needed through \`imports\` or \`globals\`; use \`modules\` for local relative ES modules; use \`execute\` to select the export and args to run. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`filename\` when supplied, including \`../\` parent paths that stay inside the supplied graph. TypeScript input is accepted by default and erased before evaluation. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive.
 
 ## Subagents
 
@@ -567,6 +590,7 @@ Prompts define system instructions, model selection, and available tools for LLM
 | \`tools\` | \`(string \\| ToolConfig)[]\` | No | Available tools: tool names, sub-prompt names, provider tools, and exposed agent names for handoffs. Subagent relationships never appear here \u2014 they are declared on the agent side's \`subagents\` array |
 | \`includeChat\` | \`boolean\` | No | Include full conversation history |
 | \`includePastTools\` | \`boolean\` | No | Include previous tool results |
+| \`historyLimit\` | \`number\` | No | With \`includeChat\`, load only the newest top-level messages: at least N and under 2N, the cut moving N at a time (prompt-cache stable). Execution history and \`filter_messages\` see only that window; stored history is untouched |
 | \`parallelToolCalls\` | \`boolean\` | No | Allow multiple concurrent tool calls |
 | \`toolChoice\` | \`'auto' \\| 'none' \\| 'required'\` | No | Tool calling strategy |
 | \`requiredSchema\` | \`z.ZodObject\` | No | Input validation when called as tool |
@@ -574,6 +598,7 @@ Prompts define system instructions, model selection, and available tools for LLM
 | \`env\` | \`Record<string, string>\` | No | Prompt-level default values for variables |
 | \`hooks\` | \`string[]\` | No | Hook IDs to run for this prompt (overrides agent hooks) |
 | \`reasoning\` | \`ReasoningConfig\` | No | Extended thinking configuration |
+| \`providerOptions\` | \`Record<string, unknown>\` | No | Provider-specific request options |
 
 ## Basic Example
 
@@ -610,6 +635,8 @@ export default definePrompt({
 });
 \`\`\`
 
+A circular prompt include raises an error that names the include chain. A prompt can include the same partial through different paths.
+
 \`type: 'env'\` inserts a resolved thread variable value. Use this only for non-secret values that are safe to expose to the LLM.
 
 The sandboxed coding prompt declares \`HTTP_HOST\` as a text variable and injects its resolved value with a structured \`{ type: 'env', property: 'HTTP_HOST' }\` prompt part. Its URL helper uses that value as the origin for files exposed from the thread \`public/\` directory and endpoints exposed from the thread \`api/\` directory. Public URLs should usually omit extensions; extensionless public paths resolve \`.html\`, then \`.js\`, then \`.ts\`, then matching \`index\` files in the same order. Browser pages should reference only public files, \`api/\` endpoints, or absolute external URLs, using relative asset URLs like \`./app\` and \`./api/todos\`; private \`src/\` files are not served directly. Public \`.ts\` files are transformed to browser JavaScript and are not server endpoints. Server-side endpoints live under the thread filesystem \`api/\` directory, and the \`api/\` directory name stays in the public URL: \`api/todo.ts\` is \`/api/threads/{threadId}/api/todo\`, while \`api/todo.ts\` is not \`/api/threads/{threadId}/todo\` or \`/api/threads/{threadId}/todos\`. Endpoint files default-export a function that accepts \`Request\` and returns \`Response\` or \`Promise<Response>\`. Endpoint code can import \`fetch\`, \`fs\`, and \`storage\`, and can import private helpers with relative paths such as \`../src/todo.ts\`. When the coding agent creates a site, page, or endpoint, it should call \`get_public_url\` with the created file path and use the returned URL.
@@ -664,7 +691,7 @@ sideA: {
 For a prompt-backed side with non-hidden relationships, the runtime automatically injects three lifecycle tools scoped to that side's declarations:
 
 - \`subagents\` \u2014 pull-based visibility: returns the registry snapshot (reference, relationship name, agent name, status, initial arguments, creation time). Call it before \`subagent_create\` so existing instances are reused rather than duplicated.
-- \`subagent_create\` \u2014 creates (or continues) an instance. Its \`agent\` argument enumerates the side's enabled relationship *names* (\`as\`, defaulting to \`agent\`), never internal agent identifiers. It requires a non-empty \`name\` for the spawned instance; AgentBuilder stores that as a \`name:<value>\` thread tag for human-friendly labels.
+- \`subagent_create\` \u2014 creates (or continues) an instance. Its \`agent\` argument enumerates the side's enabled relationship *names* (\`as\`, defaulting to the unqualified part of \`agent\`), never internal agent identifiers. It requires a non-empty \`name\` for the spawned instance; AgentBuilder stores that as a \`name:<value>\` thread tag for human-friendly labels.
 - \`subagent_message\` \u2014 queues a message to an existing instance by reference.
 
 These three names are reserved; a relationship \`as\` that collides with them (or with any other tool name) is a definition-time error.
@@ -696,8 +723,16 @@ export default definePrompt({
 });
 \`\`\`
 
+Provider options merge from model defaults to prompt overrides. Later values win.
+
 ## Extended Thinking (Reasoning)
 
+A prompt can set \`reasoning.level\` from 0 to 100. An unset level uses the model's default. Level 0 disables reasoning when the model supports a disabling control. Otherwise, the provider selects the lowest reasoning setting. A model with no reasoning control receives no control. Each provider maps the level to the nearest option the model declares.
+
+A prompt's \`reasoning.level\` replaces a native effort value in \`providerOptions\`. Other \`providerOptions\` keys remain. Without a level, \`providerOptions\` apply as provided. Native effort values in a model's \`providerOptions\` remain valid.
+
+Saved prompt input with \`reasoning.effort\` fails validation. A published package prompt with \`reasoning.effort\` loads with a warning. The runtime ignores that field.
+
 Enable for complex reasoning tasks:
 
 \`\`\`typescript
@@ -707,7 +742,7 @@ export default definePrompt({
   model: 'heavy',
   prompt: 'Review the code thoroughly...',
   reasoning: {
-    effort: 'high',      // 'low' | 'medium' | 'high'
+    level: 100,          // 0 to 100
     maxTokens: 16000,    // Max thinking tokens
     exclude: true,       // Don't include thinking in response
   },
@@ -718,7 +753,7 @@ export default definePrompt({
 
 \`\`\`typescript
 reasoning: {
-  effort: 'low',  // Can be 'low', 'medium', or 'high'
+  level: 33,  // 0 to 100
 },
 \`\`\`
 
@@ -797,8 +832,8 @@ A side's configuration is discriminated by its backing: exactly one of \`human\`
 | \`label\` | \`string\` | No | Display name for this side |
 | \`subagents\` | \`SubagentRelationship[]\` | No | Side-owned child relationships (see Subagent Relationships below) |
 | \`stopOnResponse\` | \`boolean\` | No | Stop side turn on text response without tool calls (default: true) |
-| \`stopTool\` | \`string\` | No | Tool that stops this side's turn |
-| \`stopToolResponseProperty\` | \`string\` | No | Property to extract from stop tool result |
+| \`stopTool\` | \`string\` | No | Tool that stops this side's turn when called, with or without \`stopToolResponseProperty\` |
+| \`stopToolResponseProperty\` | \`string\` | No | Property to extract from the stop tool result. This option requires \`stopTool\`. |
 | \`maxSteps\` | \`number\` | No | Maximum step budget for this side |
 | \`sessionStop\` | \`SessionToolBinding\` | No | Terminal success lifecycle binding (object form only) |
 | \`sessionFail\` | \`SessionToolBinding\` | No | Terminal failure lifecycle binding (object form only) |
@@ -913,7 +948,7 @@ sideA: {
 \`\`\`
 
 - The owning side is where child traffic lands: completion, failure, and status messages arrive on the owning side's perspective. Parent\u2192child traffic enters in the child's side B perspective (\`role: 'user'\`), so the child's side A acts on it.
-- A relationship name (\`as\`, defaulting to \`agent\`) may appear on at most one side, must not collide with another tool name, and must not collide with the reserved lifecycle tool names \`subagents\`, \`subagent_create\`, \`subagent_message\`.
+- A relationship name (\`as\`, defaulting to the unqualified part of \`agent\`) may appear on at most one side, must not collide with another tool name, and must not collide with the reserved lifecycle tool names \`subagents\`, \`subagent_create\`, \`subagent_message\`.
 - For a prompt-backed owning side, the runtime injects those lifecycle tools automatically. Handler-backed owning sides need no tool grant \u2014 handlers reach children through \`ThreadState\` directly.
 - **Persistence is universal**: every child instance is a persistent thread. Session end never terminates a thread; only explicit \`state.terminate()\` destroys an instance. \`blocking\` is purely a waiting style.
 
@@ -1201,6 +1236,10 @@ export default defineTool({
 });
 \`\`\`
 
+Tool variable definitions preserve \`scoped: true\`. A scoped variable blocks inheritance from the parent thread environment.
+
+\`defineTool()\` preserves \`annotations\` unchanged.
+
 ## Argument Schemas
 
 Tool args must be a top-level \`z.object(...)\`. Prefer explicit, bounded schemas made from strings, numbers, booleans, nulls, literals, enums, arrays, objects, optionals, nullables, and defaults. Avoid provider-visible recursive or open-ended schemas such as \`z.unknown()\`, \`z.any()\`, and \`z.object({}).catchall(...)\`; strict tool providers can reject the generated JSON Schema. If a tool needs arbitrary JSON input, accept it as a JSON string and parse it inside \`execute\`.
@@ -1246,9 +1285,8 @@ execute: async (state, args) => {
   // per-user personalization or entitlement checks. Null when user-less.
   const user = await state.user();
 
-  // Instance-GLOBAL Agent Skills library (agentskills.io SKILL.md format).
-  // Skills install once and are visible to every thread; load a skill's body
-  // only when it's applicable (progressive disclosure).
+  // A thread sees its owner's skills and enabled shared skills.
+  // Load a skill body when it applies. Mutations require an instance admin.
   const skills = await state.skills.list();
   const skill = await state.skills.get('pdf-processing');
   const script = await state.skills.readFile('pdf-processing', 'scripts/extract.py');
@@ -1270,7 +1308,7 @@ execute: async (state, args) => {
 }
 \`\`\`
 
-Use \`state.runCode()\` instead of \`eval\` or \`new Function\` for model- or user-authored JavaScript/TypeScript. The sandbox starts with no ambient host capabilities; provide imports/globals explicitly, use \`modules\` for local relative ES modules, use \`execute\` to select an export and pass args, use \`report\` for streamed observations, and call \`run.terminate(reason)\` from your own timeout budget when needed. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`options.filename\` when supplied. Relative module imports may use \`./\` and \`../\` as long as they resolve within the supplied module graph. In thread endpoints, \`runCode\` is forwarded into the thread Durable Object; pass plain transferable option values there, and do function-backed bridges from tools or in-thread execution contexts.
+Use \`state.runCode()\` instead of \`eval\` or \`new Function\` for model- or user-authored JavaScript/TypeScript. The sandbox starts with no ambient host capabilities; provide imports/globals explicitly, use \`modules\` for local relative ES modules, use \`execute\` to select an export and pass args, use \`report\` for streamed observations, and call \`run.terminate(reason)\` from your own timeout budget when needed. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`options.filename\` when supplied. Relative module imports may use \`./\` and \`../\` as long as they resolve within the supplied module graph. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive.
 
 ### Optional Runtime Streams
 
@@ -1513,11 +1551,11 @@ Hooks intercept and modify agent execution at specific lifecycle points.
 | \`after_thread_created\` | \`(state: ThreadState) => void\` | Initialize a newly created thread before execution |
 | \`after_subagent_created\` | \`(state: ThreadState, childState: ThreadState) => void\` | Run parent-side logic after a child thread is created |
 | \`after_system_message\` | \`(state: ThreadState, systemMessage: string) => string \\| null \\| undefined\` | Modify the rendered system message before the history snapshot |
-| \`filter_messages\` | \`(state: ThreadState, messages: Message[]) => Message[]\` | Build the request context from one stable history snapshot per model request |
+| \`filter_messages\` | \`(state: ThreadState, messages: Message[]) => Message[]\` | Build the request context from one stable history snapshot per model request (only the newest window when the prompt sets \`historyLimit\`) |
 | \`prefilter_llm_history\` | \`(state: ThreadState, messages: LLMMessage[]) => LLMMessage[]\` | Modify transformed provider messages before dispatch |
 | \`before_create_message\` | \`(state: ThreadState, message: Message) => Message\` | Modify message before database insert |
 | \`after_create_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message created |
-| \`before_update_message\` | \`(state: ThreadState, id: string, updates: Record) => Record\` | Modify updates before message update |
+| \`before_update_message\` | \`(state: ThreadState, id: string, updates: Record) => Record\` | Modify updates for a persisted message before its update |
 | \`after_update_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message updated |
 | \`before_store_tool_result\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult\` | Modify tool result before storage |
 | \`after_tool_call_success\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process successful tool execution |
@@ -1533,6 +1571,10 @@ first and \`HookExecutionContext\` last. The context source is prompt, agent, or
 child provenance; child provenance includes \`relationshipName\`, resolved
 \`agentName\`, and optional package signature.
 
+Packed thread hooks receive a \`ThreadState\` in their owning package namespace.
+Every hook can use \`state.loadPrompt('own')\` to load a package-local prompt.
+This includes \`before_create_message\`.
+
 ## Creating a Hook
 
 Each hook file exports a default \`defineHook\` call with three properties:
@@ -1590,6 +1632,11 @@ the current snapshot. Messages injected by either request-context hook enter the
 following snapshot. Silent messages remain eligible unless a request-context hook removes
 them.
 
+When the active prompt sets \`historyLimit\` (N), the snapshot and
+\`state.execution.messageHistory\` hold only the newest top-level rows: at least N
+and fewer than 2N, the cut moving N at a time. A hook looking for an older marker
+(a compaction summary, a task header) may not see it; stored history is untouched.
+
 ## Create-Message Lifecycle
 
 \`before_create_message\` and \`after_create_message\` run for runtime insertion
@@ -1844,10 +1891,16 @@ A public endpoint is reachable by anyone who has the URL \u2014 treat it like an
 internet-facing route: validate the path, reject early, and never echo
 private state to anonymous callers.
 
-Note: \`state.execution\` is always \`null\` in endpoints since the thread is at rest. \`state.runCode()\` is available from endpoints and is forwarded into the thread runtime; pass plain transferable option values there, and do function-backed sandbox bridges from tools or in-thread execution contexts. \`state.emit(event, data)\` broadcasts a custom WebSocket event from endpoints as well as active executions; use it as an invalidation hint after persisting durable state, not as a replacement for reconnect recovery.
+Note: \`state.execution\` is always \`null\` in endpoints since the thread is at rest. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive. \`state.emit(event, data)\` broadcasts a custom WebSocket event from endpoints as well as active executions; use it as an invalidation hint after persisting durable state, not as a replacement for reconnect recovery.
 
 ## ThreadState Methods
 
+\`getMessages()\` returns messages newest first by default. Set \`order: 'asc'\` for oldest first.
+\`getMessage(id)\` finds persisted messages at any depth. It also finds pending messages from the message list. It returns \`null\` for unknown IDs.
+\`updateMessage(id, updates)\` updates a persisted message. It returns the updated \`Message\`.
+Updates to missing or pending messages fail before update hooks run.
+Message results include \`reasoning_content\`, \`reasoning_details\`, \`prompt\`, and available subagent fields: \`subagent_id\`, \`subagent_name\`, \`subagent_title\`, \`subagent_description\`, \`subagent_status\`, \`subagent_relationship\`, \`subagent_blocking\`, \`subagent_thread_name\`, and \`subagent_spawn_group_id\`.
+
 Access thread data through the state object:
 
 \`\`\`typescript
@@ -1888,6 +1941,12 @@ export default defineThreadEndpoint(async (req, state) => {
 });
 \`\`\`
 
+\`state.loadModel\`, \`state.loadPrompt\`, and \`state.loadAgent\` enforce package
+visibility. Global code can load unpacked definitions and packed entry agents.
+Packed code can load its own definitions and other packages' entry agents.
+A packed model cannot fall back to a host model with the same short name.
+A refused load returns the same not-found error as a missing definition.
+
 ## POST with Request Body
 
 \`\`\`typescript
@@ -1898,7 +1957,7 @@ export default defineThreadEndpoint(async (req, state) => {
   const body = await req.json();
   const { format = 'json' } = body;
 
-  const { messages } = await state.getMessages();
+  const { messages } = await state.getMessages({ order: 'asc' });
 
   if (format === 'csv') {
     const csv = messages.map(m => \`\${m.role},\${m.content}\`).join('\\n');
@@ -2037,6 +2096,8 @@ the user event stream at \`/api/users/me/stream\`), \`listThreads()\`,
 \`fetch(grant, url, init)\` (privileged fetch through a credential grant), and
 \`thread(threadId)\` (raise one of the user's threads at rest).
 
+\`user.identity()\` returns a \`UserIdentity\`. Its \`username\` and \`role\` fields may be absent or null.
+
 ## User Rooms
 
 A \`users/pkg/room.ts\` file may export \`defineUserRoom\` to handle hub frames
@@ -2130,7 +2191,7 @@ var APPROVED_DEPENDENCY_BUILD_SCRIPTS = [
   "sharp",
   "workerd"
 ];
-var AGENTBUILDER_TEMPLATE_VERSION = "0.43.0";
+var AGENTBUILDER_TEMPLATE_VERSION = "0.44.0";
 var DEFAULT_TEMPLATE_VERSIONS = {
   standardAgents: `^${AGENTBUILDER_TEMPLATE_VERSION}`,
   sip: "^1.0.1",