@ziggs-ai/agent-sdk 0.16.1 → 0.17.0

package/dist/skills/parseSkill.js

@@ -8,7 +8,7 @@
  * with the agent's full authority, so "instructions-only" has to be a structural
  * property of what we accept, not a convention authors are trusted to follow.
  *
- * This module is deliberately free of AgentHost / LLM / MCP imports so it stays
+ * This module is deliberately free of Agent / LLM / MCP imports so it stays
  * unit-testable standalone (same rule as scripts/lib/mcp-provision.ts).
  */
 import { createHash } from 'node:crypto';
@@ -124,9 +124,24 @@ export function parseSkill(files, opts = {}) {
     }
     return { name: name, description: description, body, references, hash: skillHash(files) };
 }
+/** Catalog name for a reference path (`references/tone.md` → `tone`). */
+export function skillReferenceName(path) {
+    return path.replace(/^references\//, '').replace(/\.md$/, '');
+}
+/** First prose line of a reference, for the on-prompt catalog. */
+export function skillReferenceOneLine(content) {
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        return trimmed.length > 160 ? `${trimmed.slice(0, 157)}…` : trimmed;
+    }
+    return '(empty)';
+}
 /**
- * Assemble the skill's role prompt: body first, then each reference under its
- * own header.
+ * Assemble the skill's role prompt: the body, then a catalog of references.
+ * Full reference text is fetched with `skill_read_reference` — it does not
+ * ride every turn.
  *
  * This is only the ROLE block. The Ziggs protocol is prepended separately, by
  * the one place that builds a Claude-brain system prompt — a skill is never in a
@@ -134,8 +149,10 @@ export function parseSkill(files, opts = {}) {
  */
 export function skillRolePrompt(skill) {
     const parts = [skill.body];
-    for (const ref of skill.references) {
-        parts.push(`## Reference: ${ref.path.replace(/^references\//, '').replace(/\.md$/, '')}`, ref.content);
+    if (skill.references.length > 0) {
+        parts.push('## Skill references', 'These files are not in this prompt. Call skill_read_reference with the name when you need one. Do not invent their contents.', skill.references
+            .map((ref) => `- ${skillReferenceName(ref.path)}: ${skillReferenceOneLine(ref.content)}`)
+            .join('\n'));
     }
     return parts.join('\n\n');
 }

package/dist/skills/skillReadReference.d.ts

@@ -0,0 +1,6 @@
+import { type ParsedSkill } from './parseSkill.js';
+/**
+ * Fetch one skill reference by catalog name. The role prompt lists names and
+ * one line each; this is how the rest of the file is loaded.
+ */
+export declare function skillReadReferenceTool(skill: ParsedSkill): import("../tools/defineTool.js").ToolDefinition;

package/dist/skills/skillReadReference.js

@@ -0,0 +1,27 @@
+import { defineTool } from '../tools/defineTool.js';
+import { skillReferenceName, } from './parseSkill.js';
+/**
+ * Fetch one skill reference by catalog name. The role prompt lists names and
+ * one line each; this is how the rest of the file is loaded.
+ */
+export function skillReadReferenceTool(skill) {
+    const byName = new Map(skill.references.map((ref) => [skillReferenceName(ref.path), ref]));
+    return defineTool('skill_read_reference', {
+        name: {
+            type: 'string',
+            required: true,
+            description: 'Reference name from the skill catalog (filename without .md)',
+        },
+    }, async (args) => {
+        const name = String(args['name'] ?? '').trim();
+        const ref = byName.get(name);
+        if (!ref) {
+            const available = [...byName.keys()];
+            throw new Error(`unknown skill reference "${name}". Available: ${available.join(', ') || '(none)'}`);
+        }
+        return { name, path: ref.path, content: ref.content };
+    }, {
+        description: 'Read one skill reference by name. The catalog of names is in your role prompt.',
+        isGenericFallback: true,
+    });
+}

package/dist/tools/needs.js

@@ -11,8 +11,8 @@
  * Scope is agents built on this SDK.
  */
 import { toolName } from './defineTool.js';
-import { connectionListGrantsTool, connectionProxyTool } from '../server/tools/tier2/connectionTools.js';
-import { MCP_CONNECTION_TOOLS } from '../server/tools/tier2/mcpConnectionTools.js';
+import { connectionListGrantsTool, connectionProxyTool } from '../platform/tools/tier2/connectionTools.js';
+import { MCP_CONNECTION_TOOLS } from '../platform/tools/tier2/mcpConnectionTools.js';
 /**
  * A remote MCP server is stored as `provider: 'mcp'` and goes through the
  * gateway. `connection_proxy` resolves a NAMED connector and refuses it with

package/dist/tools/toolCreds.d.ts

@@ -3,7 +3,7 @@
  *
  * A custom tool builds `{ operatorKey, agentId }` by hand and stops there, so
  * every call it makes runs on the narrowest reach fence there is: the agent's
- * own org. `AgentHost` already threads the wake's lane into the tool context
+ * own org. `Agent` already threads the wake's lane into the tool context
  * (as `chatId` / `sessionId`, which is what the capability adapter reads), and
  * the backend's fence is "own org ∪ the orgs of the parties to this lane" — so
  * a tool that does not pass it loses reach it is entitled to, and loses it

package/dist/tools/toolCreds.js

@@ -3,7 +3,7 @@
  *
  * A custom tool builds `{ operatorKey, agentId }` by hand and stops there, so
  * every call it makes runs on the narrowest reach fence there is: the agent's
- * own org. `AgentHost` already threads the wake's lane into the tool context
+ * own org. `Agent` already threads the wake's lane into the tool context
  * (as `chatId` / `sessionId`, which is what the capability adapter reads), and
  * the backend's fence is "own org ∪ the orgs of the parties to this lane" — so
  * a tool that does not pass it loses reach it is entitled to, and loses it

package/dist/types.d.ts

@@ -502,7 +502,7 @@ export type Effect = {
 /**
  * Typed result map. With this shape, `await eff({ kind: 'read-context', .. })`
  * resolves to `ContextSnapshot`, not a union — the discriminant carries the
- * result type. Tests and Server impls implement this map exhaustively.
+ * result type. Tests and effect handlers implement this map exhaustively.
  */
 export interface EffectResultMap {
     'read-context': ContextSnapshot;
@@ -520,7 +520,7 @@ export interface EffectResultMap {
     };
 }
 export type EffectResult<K extends EffectKind> = EffectResultMap[K];
-/** The single side-channel between Agent and Server. */
+/** The single side-channel between a Brain and its Agent. */
 export type EffectHandler = <K extends EffectKind>(effect: Extract<Effect, {
     kind: K;
 }>) => Promise<EffectResult<K>>;
@@ -563,7 +563,7 @@ export interface DefineAgentInput {
     [key: string]: unknown;
 }
 /**
- * Frozen output of defineAgent. Consumed directly by AgentHost / createAgent.
+ * Frozen output of defineAgent. Consumed directly by Agent / createAgent.
  * defineAgent injects ONE default: the agreement-kickoff state `kickingOff`
  * plus a last-position transition into it, added to states that don't already
  * handle a proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.15.1",
+    "@ziggs-ai/api-client": "0.16.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",

package/dist/server/createHealthServer.d.ts

@@ -1,7 +0,0 @@
-import { type Server } from 'http';
-import type { ConnectionPool } from './ConnectionPool.js';
-export declare function createHealthServer({ port, label, pool, }?: {
-    port?: number;
-    label?: string;
-    pool?: ConnectionPool;
-}): Server;

package/dist/server/createHealthServer.js

@@ -1,75 +0,0 @@
-import { createServer } from 'http';
-import { runtimeLog } from '../shared/runtimeLog.js';
-function readJsonBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on('data', (c) => chunks.push(c));
-        req.on('end', () => {
-            try {
-                const raw = Buffer.concat(chunks).toString('utf8');
-                resolve(raw ? JSON.parse(raw) : {});
-            }
-            catch (err) {
-                reject(err);
-            }
-        });
-        req.on('error', reject);
-    });
-}
-export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, } = {}) {
-    const server = createServer(async (req, res) => {
-        const url = req.url ?? '/';
-        const startMatch = url.match(/^\/fleet-start\/([^/?]+)/);
-        if (req.method === 'POST' && startMatch && pool) {
-            const agentId = decodeURIComponent(startMatch[1]);
-            try {
-                await pool.startAgent(agentId);
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ok: true, agentId, active: pool.listActive().includes(agentId) }));
-            }
-            catch (err) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ok: false, error: err.message }));
-            }
-            return;
-        }
-        if (req.method === 'POST' && url === '/fleet-deliver' && pool) {
-            try {
-                const body = await readJsonBody(req);
-                const agentId = String(body.agentId ?? '');
-                const chatId = String(body.chatId ?? '');
-                const text = String(body.text ?? '');
-                const senderId = String(body.senderId ?? '');
-                if (!agentId || !chatId || !text || !senderId) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ ok: false, error: 'agentId, chatId, text, senderId required' }));
-                    return;
-                }
-                const host = (await pool.startAgent(agentId));
-                await host.handleMessage(text, {
-                    chatId,
-                    entryType: 'message',
-                    contentType: 'text',
-                    sender: { id: senderId, type: 'USER' },
-                    receiver: { id: agentId, type: 'AGENT' },
-                });
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ok: true, agentId }));
-            }
-            catch (err) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ok: false, error: err.message }));
-            }
-            return;
-        }
-        if (url === '/health' || url === '/') {
-            res.writeHead(200);
-            res.end('ok');
-            return;
-        }
-        res.writeHead(404);
-        res.end();
-    });
-    server.listen(port, () => runtimeLog.info(label, `health server on port ${port}`));
-    return server;
-}

package/dist/server/runLauncher.d.ts

@@ -1,22 +0,0 @@
-import { ConnectionPool } from './ConnectionPool.js';
-import { type AgentHostOptions } from '../AgentHost.js';
-type AgentConfig = AgentHostOptions & {
-    ownAgentId?: string;
-    options?: {
-        ownAgentId?: string;
-        name?: string;
-    };
-};
-interface SingleOptions {
-    operatorKey?: string;
-    label?: string;
-    port?: number | string;
-    healthServer?: boolean;
-    onShutdown?: () => Promise<void>;
-}
-interface FleetOptions extends SingleOptions {
-    agentMeta?: Record<string, unknown>[];
-    primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
-}
-export declare function runLauncher(configOrConfigs: AgentConfig | AgentConfig[], opts?: FleetOptions): Promise<unknown>;
-export {};

package/dist/server/runLauncher.js

@@ -1,160 +0,0 @@
-import { ConnectionPool } from './ConnectionPool.js';
-import { AgentHost } from '../AgentHost.js';
-import { createHealthServer } from './createHealthServer.js';
-import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
-import { runtimeLog } from '../shared/runtimeLog.js';
-import { PollRegistry } from './polls/PollKind.js';
-import { PollRunner } from './polls/PollRunner.js';
-/**
- * How long a shutdown waits for in-flight turns after it has stopped taking new
- * work. An agent turn is an LLM call, so the old 30s was under the length of the
- * work it was meant to protect; the container's stop timeout is what has to be
- * larger still, or the drain is cut short by SIGKILL regardless (ECS
- * `stopTimeout`, 120s on the fleet task definitions).
- */
-const DRAIN_TIMEOUT_MS = Number(process.env.FLEET_DRAIN_TIMEOUT_MS) || 90_000;
-/**
- * Collect the poll kinds the agents themselves ship and start a runner for
- * whatever they declared. This lives in the launcher, not in a caller's
- * bootstrap file: an agent that declares `polls` and gets no runner sees no
- * error and simply never wakes, which is indistinguishable from a quiet source.
- * Every launcher path therefore executes polls, or refuses loudly.
- */
-function startDeclaredPolls(configs, pool, { operatorKey, label }) {
-    const registry = new PollRegistry();
-    for (const cfg of configs) {
-        for (const kind of (cfg.pollKinds ?? [])) {
-            // Two agents may legitimately share a source; first registration wins and
-            // a duplicate id is not an error worth killing a fleet launch over.
-            if (!registry.get(kind.id))
-                registry.register(kind);
-        }
-    }
-    const runner = new PollRunner({
-        pool,
-        registry,
-        agents: configs,
-        label: `${label}-polls`,
-        ...(operatorKey ? { operatorKey } : {}),
-    });
-    if (runner.size === 0)
-        return null;
-    runner.start();
-    return runner;
-}
-export async function runLauncher(configOrConfigs, opts = {}) {
-    if (Array.isArray(configOrConfigs))
-        return runFleet(configOrConfigs, opts);
-    return runSingle(configOrConfigs, opts);
-}
-async function runSingle(config, { operatorKey, label = 'agent', port = process.env.PORT || 8080, healthServer = true, onShutdown } = {}) {
-    const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
-    const decorated = effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
-    const agent = new AgentHost(decorated);
-    try {
-        await agent.connectAsync();
-        runtimeLog.info(label, `"${agent['options'] ? (agent['options']?.agentId ?? agent['options']?.name) : 'agent'}" connected`);
-    }
-    catch (err) {
-        runtimeLog.warn(label, `Agent failed to connect at startup: ${err.message} — will retry`);
-    }
-    const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
-    // One agent, so the "pool" is just this host.
-    const pollRunner = startDeclaredPolls([decorated], { sendTo: (_agentId, text, metadata) => agent.handleMessage(text, metadata ?? {}) }, { label, ...(effectiveKey ? { operatorKey: effectiveKey } : {}) });
-    process.on('SIGTERM', async () => {
-        runtimeLog.info(label, 'SIGTERM — shutting down');
-        pollRunner?.stop();
-        agent.disconnect();
-        await agent.drain(DRAIN_TIMEOUT_MS);
-        try {
-            await onShutdown?.();
-        }
-        catch (err) {
-            runtimeLog.warn(label, `onShutdown error: ${err.message}`);
-        }
-        server?.close();
-        process.exit(0);
-    });
-    return { agent, healthServer: server ?? undefined };
-}
-async function runFleet(configs, { operatorKey, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, onShutdown, } = {}) {
-    const pool = new ConnectionPool();
-    const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
-    const decoratedConfigs = effectiveKey
-        ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
-        : configs;
-    pool.register(decoratedConfigs, agentMeta);
-    const server = healthServer ? createHealthServer({ port: Number(port), label, pool }) : null;
-    let resolvedPrimaryConfig = typeof primaryConfig === 'function'
-        ? primaryConfig(pool)
-        : primaryConfig;
-    if (resolvedPrimaryConfig && effectiveKey && !resolvedPrimaryConfig.operatorKey) {
-        resolvedPrimaryConfig = { ...resolvedPrimaryConfig, operatorKey: effectiveKey };
-    }
-    const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedPrimaryConfig?.operatorKey;
-    if (controlKey) {
-        // an agent-bound key half-works in a confusing way — say the big
-        // thing once at startup instead of letting N-1 per-agent loops 403.
-        const boundWarning = boundKeyFleetWarning(controlKey, pool.size);
-        if (boundWarning)
-            runtimeLog.warn(label, boundWarning);
-    }
-    let primary = null;
-    if (resolvedPrimaryConfig) {
-        primary = new AgentHost(resolvedPrimaryConfig);
-        try {
-            await primary.connectAsync();
-            runtimeLog.info(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" connected`);
-        }
-        catch (err) {
-            // Backend may not be ready yet — the inbox long-poll loop retries on
-            // the next pass. Don't crash the process.
-            runtimeLog.warn(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${err.message} — will retry`);
-        }
-    }
-    // Every registered agent connects. There is no roster to consult
-    // and no reason to defer: an agent this launcher was handed is an agent it
-    // hosts, and each host's own inbox long-poll is the only wake signal needed.
-    await pool.connectAll();
-    const connected = pool.listActive().length;
-    if (connected < pool.size) {
-        // Say it loudly and with the number. A launcher that silently hosts fewer
-        // agents than it was given is exactly how three published, hireable agents
-        // ran with no host and nothing noticed.
-        runtimeLog.warn(label, `Only ${connected}/${pool.size} agent(s) connected — the rest are registered but unhosted`);
-    }
-    runtimeLog.info(label, `Ready — ${connected}/${pool.size} agent(s) connected`);
-    const pollRunner = startDeclaredPolls(decoratedConfigs, pool, {
-        label,
-        ...(effectiveKey ? { operatorKey: effectiveKey } : {}),
-    });
-    process.on('SIGTERM', async () => {
-        runtimeLog.info(label, 'SIGTERM — shutting down');
-        // Stop taking new work everywhere first, then wait for what is running.
-        //
-        // This used to disconnect and drain only `primary` — which `run.ts` never
-        // sets, so in the deployed fleet the drain was a no-op on null and the
-        // process exited straight through `disconnectAll`, killing every in-flight
-        // turn. A buyer whose request landed mid-rollout got a host that stopped
-        // mid-sentence and never reported.
-        //
-        // Draining before stopping intake is the other half of the same bug: the
-        // wait is exactly the window in which a host on its way out keeps accepting
-        // deliveries the incoming host is also being handed.
-        pollRunner?.stop();
-        primary?.disconnect?.();
-        await Promise.all([
-            pool.shutdown(DRAIN_TIMEOUT_MS),
-            primary?.drain?.(DRAIN_TIMEOUT_MS) ?? Promise.resolve(),
-        ]);
-        try {
-            await onShutdown?.();
-        }
-        catch (err) {
-            runtimeLog.warn(label, `onShutdown error: ${err.message}`);
-        }
-        server?.close();
-        process.exit(0);
-    });
-    return { pool, primary, healthServer: server ?? undefined };
-}