@standardagents/skill 0.41.0 → 0.41.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.41.0",
+  "version": "0.41.1",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -501,6 +501,45 @@ export default defineAgent({
 
 The child's answers arrive as inbound messages on side A — the relationship's owning side — and get their own handler turns, where the handler calls the project's outbound messaging tool. The handler forwards with `queueMessage` rather than a blocking spawn: a handler that awaits a blocking child session holds its thread's one-at-a-time delivery slot for the whole session. Note the handler side declares its child but needs no tool grants — the side's declaration is the grant, and the handler reaches children through `ThreadState` directly.
 
+### Worked example: thread-open choreography (bootstrap, then speak first)
+
+"Run some tools when a thread opens, then have the agent greet first" is a common shape (load a profile, generate an asset, fetch context). There is no auto-run flag on prompt tools — the pattern is **hook schedules effect; effect does the work; effect queues a kickoff**:
+
+```typescript
+// agents/hooks/buddy_bootstrap.ts — enqueue only; thread creation returns instantly
+export default defineHook({
+  hook: 'after_thread_created',
+  id: 'buddy_bootstrap',
+  execute: async (state) => {
+    await state.scheduleEffect('buddy_bootstrap', {}, 0);
+  },
+});
+
+// agents/effects/buddy_bootstrap.ts — the observable work
+export default defineEffect(
+  'Bootstrap a fresh thread with its profile and avatar.',
+  async (state) => {
+    await state.invokeTool('update_profile', {});
+    await state.invokeTool('create_avatar', {});
+    // Speak first: a silent side-B-perspective message wakes side A for a
+    // normal turn. Silent hides the instruction; the greeting is a regular
+    // visible assistant message.
+    await state.queueMessage({
+      role: 'user',
+      silent: true,
+      content: 'The chat just opened. Greet the user warmly in one short message, using the profile you just loaded. Do not mention this instruction.',
+    });
+  },
+);
+```
+
+Register the hook id in the side A prompt's `hooks` array. Why this split and not simpler alternatives:
+
+- **Do NOT run the tools directly in the hook** (`await state.invokeTool(...)` inside `after_thread_created`): the hook is awaited during thread creation, so `POST /api/threads` stalls until every tool — including any image generation — finishes. Scheduling the effect takes milliseconds; the work then runs as a normal execution the log pane shows live.
+- **Do NOT reach for `queueTool` from the hook**: it fires an unawaited background promise across the creating object's boundary, which can be cancelled. `scheduleEffect` is durable.
+- The kickoff races an instant first user message — design the prompt so a missing profile degrades gracefully (e.g. an `after_system_message` hook that injects "profile missing, load it now").
+- For subagent children this pattern is unnecessary — `SubagentRelationship.immediate` already spawns instances at thread creation. This recipe is for running the agent's OWN tools at open.
+
 ---
 
 ## Model selection
@@ -513,6 +552,7 @@ The child's answers arrive as inbound messages on side A — the relationship's
 2. Choose the category that fits the role (table below).
 3. Run `pnpm exec agents available-models --provider=<name>` to confirm the exact provider model string.
 4. Define the model in `agents/models/<name>.ts` using `defineModel`.
+5. Take `capabilities` from the provider (`POST /api/models/capabilities` with `{provider, modelId}`, or the admin model picker) — **never guess them, and never flatter the model.** The runtime's vision filter trusts `supportsImages`: declare it `true` on a text-only model and generated-image attachments ship to the provider as raw base64 that gets tokenized as *text* — a ~1MB PNG becomes ~1.2M input tokens and every turn after the first image hard-fails with "input too long". Declared `false`, images become a small placeholder in requests while stored history keeps the real files.
 
 If you have multiple configured providers, pass `--provider=<name>` explicitly.
 
@@ -738,6 +778,10 @@ Two things that are deliberately **not** tools:
 - **Subagent relationships** are declared on a side's `subagents` array, never in a prompt's `tools` array — a `tools` entry attempting to configure one is a definition-time error. The prompt backing an owning side automatically receives the injected lifecycle tools (`subagents`, `subagent_create`, `subagent_message`) for that side's non-hidden relationships; their names are reserved.
 - **Handlers** own a side's turns and may not be referenced by prompt `tools` arrays, hook lists, or effect schedules.
 
+### Zod version pinning
+
+The published `@standardagents/spec` type declarations embed the zod instance they were built against (zod v4 types are version-branded). If your project resolves a different zod, every `z.object(...)` you pass to `requiredSchema`/tool `args` fails with baffling `ZodObject<..., $strict> is not assignable to ToolArgs<N>` errors. Pin your project's `zod` (dependency + a `pnpm.overrides` entry) to the version the installed spec package resolves — check `node_modules/@standardagents/spec/node_modules/zod/package.json` or the spec's lockfile entry — instead of `latest`.
+
 ### Provider-visible argument schemas
 
 Tool argument schemas are sent to model providers, and strict tool-calling providers commonly reject JSON Schema objects unless every object schema has `additionalProperties: false`. This applies recursively, not just at the top level. If a tool has nested object args, arrays of objects, `anyOf` object branches, prompt `requiredSchema`, or an agent exposed as a tool, verify the model-facing schema contains `additionalProperties: false` for every `type: "object"`.