@ziggs-ai/agent-sdk 0.10.8 → 0.11.1

package/dist/tools/needs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * Scope is agents built on this SDK.
+ */
+import { type ToolDefinition } from './defineTool.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
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export declare const MCP_PROVIDER = "mcp";
+/**
+ * One shape for now, the one we have actually hit. A second kind means a case in
+ * {@link toolsForNeed}: a need nothing derives tools from is a need nothing
+ * enforces.
+ */
+export interface ConnectionNeed {
+    /** Provider, e.g. 'mcp' or a named connector like 'github'. */
+    connection: string;
+}
+export type AgentNeed = ConnectionNeed;
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export declare function normalizeNeeds(input: unknown): AgentNeed[];
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export declare function toolsForNeed(need: AgentNeed): ToolDefinition[];
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export declare function toolsForNeeds(needs: AgentNeed[]): ToolDefinition[];
+/** One line naming what is missing, for a refusal a human can act on. */
+export declare function describeNeed(need: AgentNeed): string;
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export declare function unmetNeeds(needs: AgentNeed[], providers: Array<string | null | undefined>): AgentNeed[];
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export declare function unmetNeedsMessage(unmet: AgentNeed[]): string;

package/dist/tools/needs.js

@@ -0,0 +1,84 @@
+/**
+ * needs.ts — what an agent cannot work without, declared once.
+ *
+ * An agent is otherwise two hand-written lists — instructions and tools — with
+ * nothing checking they agree, so a prompt can promise work the toolset has no
+ * way to do and the mismatch only surfaces on a real hire. A third list to
+ * compare against the other two would drift the same way, so the declaration
+ * DERIVES the tools instead. The author never writes that part of the list, so
+ * the mismatch cannot be written.
+ *
+ * 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';
+/**
+ * A remote MCP server is stored as `provider: 'mcp'` and goes through the
+ * gateway. `connection_proxy` resolves a NAMED connector and refuses it with
+ * "Unknown provider: mcp" — the second wall linear-janitor hit.
+ */
+export const MCP_PROVIDER = 'mcp';
+/** Reads a manifest's `needs` field defensively — it crosses a package edge. */
+export function normalizeNeeds(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const raw of input) {
+        const connection = raw?.connection;
+        if (typeof connection === 'string' && connection.trim()) {
+            out.push({ connection: connection.trim() });
+        }
+    }
+    return out;
+}
+/**
+ * The tools a stated need implies. `connection_list_grants` rides every need
+ * because seeing the grant is half of using it: the janitor's first failure was
+ * an agent that held a Linear grant and had no way to notice.
+ */
+export function toolsForNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? [connectionListGrantsTool, ...MCP_CONNECTION_TOOLS]
+        : [connectionListGrantsTool, connectionProxyTool];
+}
+/** Deduped by tool name, so overlapping needs (and a hand-listed tool) merge. */
+export function toolsForNeeds(needs) {
+    const byName = new Map();
+    for (const need of needs) {
+        for (const tool of toolsForNeed(need)) {
+            const name = toolName(tool);
+            if (name)
+                byName.set(name, tool);
+        }
+    }
+    return [...byName.values()];
+}
+/** One line naming what is missing, for a refusal a human can act on. */
+export function describeNeed(need) {
+    return need.connection === MCP_PROVIDER
+        ? 'a connection to an MCP server'
+        : `a ${need.connection} connection`;
+}
+/**
+ * Which declared needs have no live grant behind them.
+ *
+ * `providers` are the providers of the agent's live connection grants. The label
+ * a grant carries is the provider, sometimes suffixed with the owner's account
+ * ("github — acme/infra"), so the provider is the part before the separator.
+ */
+export function unmetNeeds(needs, providers) {
+    const held = new Set(providers
+        .map((p) => String(p ?? '').split('—')[0].trim().toLowerCase())
+        .filter(Boolean));
+    return needs.filter((n) => !held.has(n.connection.toLowerCase()));
+}
+/**
+ * The refusal itself. Names the missing access and who can fix it, because the
+ * agent cannot: issuing a connection grant is the connection owner's act.
+ */
+export function unmetNeedsMessage(unmet) {
+    const list = unmet.map(describeNeed).join(', ');
+    return (`Cannot start this task: no live grant for ${list}. ` +
+        'Ask the connection owner to issue one for this agent, then re-assign the task.');
+}

package/dist/tools/recordReport.d.ts

@@ -1,6 +1,6 @@
 import { type Creds } from '@ziggs-ai/api-client';
 /**
- * The canonical report shape (B1 convention — ZIG-561).
+ * The canonical report shape (B1 convention).
  * Matches Task.result as set by ziggs_task_set_result.
  */
 export interface TaskReport {
@@ -13,7 +13,7 @@ export interface RecordReportInput {
     taskId: string;
     report: TaskReport;
     /**
-     * Optional container for the deliverable artifact (ZIG-1037 — it used to be
+     * Optional container for the deliverable artifact (it used to be
      * required). The task binding is what makes the deliverable retrievable and
      * readable by the task's parties; a chat or agreement only widens where it also
      * shows up. Pass at most one; when both arrive, agreementId wins.
@@ -32,7 +32,7 @@ export interface RecordReportResult {
     artifactId?: string;
 }
 /**
- * Record a conformant report for a completed task (B2 — ZIG-562).
+ * Record a conformant report for a completed task (B2).
  *
  * Always sets Task.result via updateTaskState (the canonical done payload).
  * When `deliverable` is provided, also writes a task-bound result artifact

package/dist/tools/recordReport.js

@@ -1,6 +1,6 @@
 import { ArtifactsClient, updateTaskState, } from '@ziggs-ai/api-client';
 /**
- * Record a conformant report for a completed task (B2 — ZIG-562).
+ * Record a conformant report for a completed task (B2).
  *
  * Always sets Task.result via updateTaskState (the canonical done payload).
  * When `deliverable` is provided, also writes a task-bound result artifact
@@ -10,11 +10,11 @@ import { ArtifactsClient, updateTaskState, } from '@ziggs-ai/api-client';
  */
 export async function recordReport(input) {
     const { creds, taskId, report, chatId, agreementId, deliverable } = input;
-    // ZIG-1037: no container needed. The deliverable is bound to its task, which
+    // no container needed. The deliverable is bound to its task, which
     // is what makes it retrievable as `via=task:<taskId>` and readable by the
     // task's parties — a chat or agreement was never what made that work.
     //
-    // ZIG-1075: the agreement still wins here, and this is now the ONE place that
+    // the agreement still wins here, and this is now the ONE place that
     // resolves rather than refuses — deliberately, because the caller is not a
     // model choosing arguments. `recordReport` is handed both ids by the runtime
     // (the task's agreement and the chat it is running in), so there is no

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * One outcome vocabulary, one ctx shape, one transition signature.
  * Every state — parked or thinking — re-enters with exactly one Outcome.
  */
+import type { AgentNeed } from './tools/needs.js';
 export interface AgreementRef {
     agreementId: string;
     parties?: {
@@ -70,7 +71,7 @@ export type Outcome = {
 } | {
     kind: 'task-closed';
     status: 'completed' | 'failed';
-    /** Task being closed — required to clear only that entry (ZIG-977). */
+    /** Task being closed — required to clear only that entry. */
     taskId?: string;
     result?: unknown;
 } | {
@@ -95,7 +96,7 @@ export type Outcome = {
      */
     proposedByMe: boolean;
     /**
-     * ZIG-1278 — true when the wake was a chat-less store/listing claim
+     * true when the wake was a chat-less store/listing claim
      * (`resource_changed` + `reason === 'proposal_approved'`). Distinguishes
      * the provider claim-kickoff (open chat + greet) from a direct-proposal
      * counterparty approve, which must never auto-kickoff.
@@ -162,7 +163,7 @@ export interface CollectedSubtaskResult {
 }
 /**
  * Per-assigned-task (or coordinator-lane) bookkeeping under one chat lane.
- * Keyed on Ctx.tasks by taskId (ZIG-977) — task-closed clears only its entry.
+ * Keyed on Ctx.tasks by taskId — task-closed clears only its entry.
  */
 export interface TaskBookkeeping {
     agreementId: string | null;
@@ -179,7 +180,7 @@ export interface TaskBookkeeping {
  * Task bookkeeping lives in `tasks` (keyed by taskId). `activeTaskId` /
  * `activeAgreementId` are the focus scalars for prompt + FSM convenience —
  * assigning task B no longer destroys task A's pending/collected state, and
- * closing A leaves B intact (ZIG-977).
+ * closing A leaves B intact.
  */
 export interface Ctx {
     identity: Identity;
@@ -202,7 +203,7 @@ export interface Ctx {
      * Recent wake timestamps (epoch ms) for this lane (claude-sdk cognition
      * only). Backstop circuit breaker: if a lane wakes faster than any real
      * traffic could drive it, the brain skips the LLM instead of burning the
-     * fleet key on a wake storm.
+     * key on a wake storm.
      */
     recentDeliveries?: number[];
 }
@@ -276,7 +277,7 @@ export interface ThinkingState {
     allowNoWait?: boolean;
 }
 /**
- * ZIG-764: fixed tool invoke with no LLM turn. Entered after transitions
+ * fixed tool invoke with no LLM turn. Entered after transitions
  * (e.g. task-assigned → executing); runs `tool` once and emits `produces`.
  */
 export interface MechanicalState {
@@ -340,7 +341,7 @@ export interface ContextSnapshot {
      * 404'd) — deleted or never visible to this agent. Message-triggered wakes
      * check this and skip the LLM instead of reasoning over a fabricated empty
      * history. Only gates message wakes. A bare agreementId as sessionId also
-     * trips it (ZIG-975) — that is a mis-keyed lane, not a legitimate task lane;
+     * trips it — that is a mis-keyed lane, not a legitimate task lane;
      * task wakes should key on the agreement's origin/notification chat.
      */
     chatMissing?: boolean;
@@ -364,7 +365,7 @@ export interface ToolCallResult {
     /**
      * Summed token usage of any nested LLM call the tool made (e.g. llmTool).
      * Threaded up so the turn's authoritative token count (machine.tokens ->
-     * result.metrics) includes tool-internal spend rather than leaking it (ZIG-813).
+     * result.metrics) includes tool-internal spend rather than leaking it.
      */
     usage?: LlmResponse['usage'];
 }
@@ -385,7 +386,7 @@ export interface DeliveryWriteKeys {
     readonly wakeKey: string | null;
     /**
      * Key for an artifact write of this wake. Pass the artifact's content so the
-     * key is derived from it (ZIG-1045 semantics): a wake writing several
+     * key is derived from it (semantics): a wake writing several
      * artifacts gets several keys, and a redelivered wake that re-writes the same
      * content reuses its key instead of colliding on an ordinal slot and being
      * discarded. Omitting content falls back to a per-wake ordinal — call exactly
@@ -397,7 +398,7 @@ export interface DeliveryWriteKeys {
     /**
      * Default messageId for a chat-message send of this wake — the backend dedups
      * on (chatId, messageId). Derived from the emission's content (text + chat +
-     * receiver), not a per-wake ordinal (ZIG-1045): a wake that says two things
+     * receiver), not a per-wake ordinal: a wake that says two things
      * gets two keys, and a redelivered wake that re-says the same text reuses the
      * same key, while a re-think with different text does not collide and drop.
      */
@@ -437,11 +438,11 @@ export type Effect = {
     kind: 'llm-call';
     messages: LlmMessage[];
     tools: LlmToolSchema[];
-    /** Chat/session id for monitoring ingest (ZIG-360). */
+    /** Chat/session id for monitoring ingest. */
     sessionId?: string;
-    /** Per-turn UUID grouping all LLM + tool calls in one turn (ZIG-440). */
+    /** Per-turn UUID grouping all LLM + tool calls in one turn. */
     runId?: string;
-    /** FSM state name at the time of this call (ZIG-440). */
+    /** FSM state name at the time of this call. */
     stateId?: string;
 } | {
     kind: 'stream-text';
@@ -459,15 +460,15 @@ export type Effect = {
     senderId?: string;
     senderType?: string;
     /**
-     * Agreement this tool call is acting under (ZIG-831). For a delegated
+     * Agreement this tool call is acting under. For a delegated
      * per-user MCP call, `senderId` is the delegating agent, not the end-user
      * who owns the connection; this lets the gateway resolve the delegation
      * root's user. Sourced from the waking task event's `result.agreementId`.
      */
     onBehalfOfAgreementId?: string;
-    /** Per-turn UUID (ZIG-440). */
+    /** Per-turn UUID. */
     runId?: string;
-    /** FSM state name (ZIG-440). */
+    /** FSM state name. */
     stateId?: string;
     /** Replay-stable write keys for this wake — write-capable tools derive their idempotency key from here, never from the LLM. */
     writeKeys?: DeliveryWriteKeys;
@@ -484,7 +485,7 @@ export type Effect = {
     idempotencyKey?: string;
 };
 /**
- * Typed result map. With this shape, `await eff({ kind: 'read-context', ... })`
+ * 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.
  */
@@ -520,7 +521,7 @@ export interface DefineAgentInput {
     /**
      * Human-facing one-liner: what this agent does, for a buyer reading the store
      * row. NOT the system prompt — a claude-sdk agent puts its prompt in
-     * `systemPrompt` (ZIG-1080: every claude-sdk agent used to pass its prompt
+     * `systemPrompt` (every claude-sdk agent used to pass its prompt
      * here, and `deriveAgentRecord` published it straight to the store).
      */
     description: string;
@@ -534,6 +535,13 @@ export interface DefineAgentInput {
     initial: string;
     states: Record<string, State>;
     tools?: unknown[];
+    /**
+     * Access this agent cannot work without. Declaring a need PRODUCES the tools
+     * for it — do not also hand-list them — and makes work that arrives without
+     * the grant fail at task start with the missing thing named, instead of
+     * part-way through a real hire.
+     */
+    needs?: AgentNeed[];
     services?: ServicesConfig;
     operatorKey?: string;
     taskTools?: 'all' | 'none' | string[];
@@ -557,6 +565,8 @@ export interface AgentConfig {
     systemPrompt?: string;
     specialization?: string;
     tools: unknown[];
+    /** Normalized declared needs — see DefineAgentInput.needs. */
+    needs?: AgentNeed[];
     model: string;
     workflow: Workflow;
     services?: ServicesConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.10.8",
+  "version": "0.11.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepack": "npm run build",
+    "prepack": "rm -rf dist && npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --experimental-test-module-mocks --import tsx/esm --test --test-reporter=spec test/*.test.ts",
     "test:watch": "node --experimental-test-module-mocks --import tsx/esm --test --watch test/*.test.ts"
@@ -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.9.8",
+    "@ziggs-ai/api-client": "0.10.4",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",