@ziggs-ai/agent-sdk 0.2.1 → 0.2.2

package/dist/AgentHost.d.ts

@@ -75,6 +75,15 @@ export interface AgentHostOptions {
     cognition?: CognitionKind;
     /** Max agentic turns per Claude SDK wake. Default 30. */
     claudeMaxTurns?: number;
+    /**
+     * ZIG-860: claude-sdk agents resume their transcript across wakes by default,
+     * so per-wake input grows monotonically on a long lane. When true, each wake
+     * starts a fresh Claude session — the protocol is backend-authoritative (the
+     * brain re-reads via ziggs_context_snapshot / the wake event), so the
+     * transcript is convenience memory, not source of truth. Ideal for
+     * step-driven orchestrators whose every wake already carries what it needs.
+     */
+    claudeStatelessPerWake?: boolean;
     services?: AgentServices;
     workflow?: Workflow;
     states?: Workflow['states'];

package/dist/AgentHost.js

@@ -144,6 +144,7 @@ export class AgentHost {
             brain: resolved.brain,
             cognition: resolved.cognition ?? 'fsm',
             claudeMaxTurns: resolved.claudeMaxTurns,
+            claudeStatelessPerWake: resolved.claudeStatelessPerWake,
         };
         this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
@@ -247,6 +248,7 @@ export class AgentHost {
                 // eff({ kind: 'tool-call' }) → the shared executor, which sources those
                 // services from the effect handler's deps like the FSM path (ZIG-775).
                 maxTurns: this.options.claudeMaxTurns,
+                statelessPerWake: this.options.claudeStatelessPerWake,
             })
             : new Agent({
                 workflow,

package/dist/adapters/McpAdapter.js

@@ -1,6 +1,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { AgentHost } from '../AgentHost.js';
 import { thinkingDefaults } from '../runtime/defaults.js';
 /**
@@ -368,21 +369,21 @@ export async function createMcpAgent(options) {
             if (!transportConfig.serverUrl)
                 return null;
             const operatorKey = transportConfig.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
-            const res = await fetch(`${backendBase}/connections/mcp/requests`, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${operatorKey}`,
-                    'x-agent-id': agentId,
-                    'x-on-behalf-of-user': userId,
-                },
-                body: JSON.stringify({
+            if (!operatorKey)
+                return null;
+            try {
+                const body = await new ConnectionsClient(operatorKey, agentId, backendBase).requestMcpConnection({
                     serverUrl: transportConfig.serverUrl,
                     tools: tools.map(t => t.name),
-                }),
-            });
-            const body = (await res.json().catch(() => null));
-            return body?.request?.requestId ?? null;
+                    onBehalfOfUserId: userId,
+                });
+                return (body?.request?.requestId) ?? null;
+            }
+            catch {
+                // Best-effort: the backend dedups pending requests and the caller falls
+                // back to a plain Connections-page link when there's no requestId.
+                return null;
+            }
         };
         const caller = async (name, args, context) => {
             const userId = typeof context.senderId === 'string' ? context.senderId : undefined;

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -13,6 +13,10 @@ export interface ClaudeSdkAgentOptions {
     operatorKey: string;
     agentId: string;
     maxTurns?: number;
+    /** ZIG-860: when true, never resume the prior Claude session — each wake is a
+     *  fresh transcript. Keeps per-wake input flat on step-driven orchestrators
+     *  whose wakes already carry their state. */
+    statelessPerWake?: boolean;
     /** Injectable for tests. Defaults to @anthropic-ai/claude-agent-sdk query(). */
     queryFn?: typeof query;
 }
@@ -32,6 +36,7 @@ export declare class ClaudeSdkAgent {
     private operatorKey;
     private agentId;
     private maxTurns;
+    private statelessPerWake;
     private queryFn;
     constructor(opts: ClaudeSdkAgentOptions);
     tick({ event, ctx, state, identity, eff }: TickInput): Promise<TickOutput>;

package/dist/agent/ClaudeSdkAgent.js

@@ -141,6 +141,7 @@ export class ClaudeSdkAgent {
     operatorKey;
     agentId;
     maxTurns;
+    statelessPerWake;
     queryFn;
     constructor(opts) {
         if (!opts.workflow?.states)
@@ -158,6 +159,7 @@ export class ClaudeSdkAgent {
         this.operatorKey = opts.operatorKey;
         this.agentId = opts.agentId;
         this.maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        this.statelessPerWake = opts.statelessPerWake ?? false;
         this.queryFn = opts.queryFn ?? query;
     }
     async tick({ event, ctx, state, identity, eff }) {
@@ -248,7 +250,10 @@ export class ClaudeSdkAgent {
                 if (line)
                     runtimeLog.warn('ClaudeSdkAgent', `stderr session=${identity.sessionId}: ${line}`);
             },
-            resume: nextCtx.claudeSessionId,
+            // ZIG-860: stateless-per-wake never resumes — each wake is a fresh
+            // transcript, so per-wake input stays flat instead of replaying the
+            // whole lane history every turn.
+            resume: this.statelessPerWake ? undefined : nextCtx.claudeSessionId,
         });
         let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
         let sessionId = nextCtx.claudeSessionId;
@@ -298,7 +303,12 @@ export class ClaudeSdkAgent {
             runtimeLog.warn('ClaudeSdkAgent', `query failed session=${identity.sessionId}: ${err.message}`);
             throw err;
         }
-        if (sessionId)
+        // Stateless-per-wake keeps no session id — clear any carried over from the
+        // prior ctx so the next wake starts fresh too (ZIG-860). Otherwise remember
+        // this wake's session for resume.
+        if (this.statelessPerWake)
+            nextCtx.claudeSessionId = undefined;
+        else if (sessionId)
             nextCtx.claudeSessionId = sessionId;
         // ZIG-816: bound resumed-transcript growth. `metrics.tokens.input` is the
         // wake's billable input off the result message (dominated by the resumed

package/dist/agent/claudeCognition.d.ts

@@ -63,5 +63,12 @@ export declare function summarizeContext(snap: Record<string, unknown> | null |
  * Turn a Ziggs wake event + context digest into the user prompt that starts a
  * Claude-brain turn. The agent's standing instructions come from its system
  * prompt (protocol + role); this is just "here's what woke you, go handle it."
+ *
+ * ZIG-880: EventQueue coalesces events that arrive while the lane is busy into
+ * a `{type:'batch', events:[...]}` frame. The FSM path unwraps those
+ * (PromptBuilder), but this path used to render just "Event type: batch" —
+ * every payload inside (including task results) was invisible to the model,
+ * stalling delegation pipelines whose notifications share one chat lane.
+ * Render each batched event in order instead.
  */
 export declare function buildClaudeEventPrompt(event: RawEvent | undefined, contextSummary: string): string;

package/dist/agent/claudeCognition.js

@@ -1,3 +1,4 @@
+import { getBatchEvents } from '../context/batch.js';
 const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6';
 /**
  * Pick the Claude model for a Claude-brain wake. The brain must run a `claude-*`
@@ -67,13 +68,8 @@ export function summarizeContext(snap) {
     const users = Array.isArray(snap.users) ? snap.users.length : 0;
     return `history=${history} messages, agreements=${agreements}, users=${users}`;
 }
-/**
- * Turn a Ziggs wake event + context digest into the user prompt that starts a
- * Claude-brain turn. The agent's standing instructions come from its system
- * prompt (protocol + role); this is just "here's what woke you, go handle it."
- */
-export function buildClaudeEventPrompt(event, contextSummary) {
-    const lines = ['You received a new Ziggs event. Handle it per your protocol.'];
+/** Render ONE event's fields into prompt lines (shared by single and batch frames). */
+function renderEventLines(event, lines) {
     if (event?.type)
         lines.push(`Event type: ${event.type}`);
     if (event?.text)
@@ -94,6 +90,41 @@ export function buildClaudeEventPrompt(event, contextSummary) {
             lines.push(`Agreement: ${result.agreementId}`);
         if (typeof result.state === 'string')
             lines.push(`Task state: ${result.state}`);
+        // ZIG-860: surface the task's RESULT payload too. Completion notifies now
+        // pin it (backend), and an orchestrator consuming a worker's output has no
+        // task-read tool — without this line the step outcome never reaches the
+        // model and a chained pipeline stalls right after its first task.
+        if (result.result != null) {
+            const payload = typeof result.result === 'string' ? result.result : JSON.stringify(result.result);
+            const MAX = 12_000;
+            lines.push(`Task result: ${payload.length > MAX ? `${payload.slice(0, MAX)} …[truncated ${payload.length - MAX} chars]` : payload}`);
+        }
+    }
+}
+/**
+ * Turn a Ziggs wake event + context digest into the user prompt that starts a
+ * Claude-brain turn. The agent's standing instructions come from its system
+ * prompt (protocol + role); this is just "here's what woke you, go handle it."
+ *
+ * ZIG-880: EventQueue coalesces events that arrive while the lane is busy into
+ * a `{type:'batch', events:[...]}` frame. The FSM path unwraps those
+ * (PromptBuilder), but this path used to render just "Event type: batch" —
+ * every payload inside (including task results) was invisible to the model,
+ * stalling delegation pipelines whose notifications share one chat lane.
+ * Render each batched event in order instead.
+ */
+export function buildClaudeEventPrompt(event, contextSummary) {
+    const lines = ['You received a new Ziggs event. Handle it per your protocol.'];
+    const batched = getBatchEvents(event);
+    if (event && batched.length > 1) {
+        lines.push(`This wake carries ${batched.length} coalesced events (oldest first). Handle them together — act once per distinct piece of work, not once per notification.`);
+        batched.forEach((e, i) => {
+            lines.push('', `— Event ${i + 1} of ${batched.length} —`);
+            renderEventLines(e, lines);
+        });
+    }
+    else {
+        renderEventLines(event, lines);
     }
     if (contextSummary) {
         lines.push('', 'Session context snapshot:', contextSummary);

package/dist/agent/claudeSdkTools.js

@@ -1,10 +1,17 @@
 import { randomUUID } from 'node:crypto';
 import { defineTool } from '../tools/defineTool.js';
+import { listGrantsTool } from '../server/tools/tier2/grantsTools.js';
+// ZIG-860: default message-history cap. An uncapped snapshot returns the whole
+// chat — in a delegation chat that accumulates notification rows, every wake's
+// snapshot ballooned (observed 35–47k input tokens/wake, ~205k/run). 12 recent
+// messages cover "what woke me and what was just said"; the model can pass a
+// larger maxMessages explicitly when it genuinely needs deeper history.
+const DEFAULT_SNAPSHOT_MAX_MESSAGES = 12;
 // Named distinctly from ziggs-mcp's per-type `ziggs_read_context`: this is the
 // one-shot aggregate snapshot (grant-fenced server-side), not a cursored read.
 export const ziggsContextSnapshotTool = defineTool('ziggs_context_snapshot', {
     chatId: { type: 'string', description: 'Chat/session id. Defaults to the current lane session.' },
-    maxMessages: { type: 'number', description: 'Optional message history cap.' },
+    maxMessages: { type: 'number', description: `Message history cap (default ${DEFAULT_SNAPSHOT_MAX_MESSAGES}). Pass a larger value when you need deeper history.` },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
@@ -15,7 +22,9 @@ export const ziggsContextSnapshotTool = defineTool('ziggs_context_snapshot', {
     return c.eff({
         kind: 'read-context',
         sessionId,
-        opts: args.maxMessages != null ? { maxMessages: Number(args.maxMessages) } : undefined,
+        opts: {
+            maxMessages: args.maxMessages != null ? Number(args.maxMessages) : DEFAULT_SNAPSHOT_MAX_MESSAGES,
+        },
     });
 }, { description: 'Read the chat snapshot: history, agreements, agents, and users for a session.' });
 export const ziggsSendMessageTool = defineTool('ziggs_send_message', {
@@ -51,7 +60,13 @@ export const ziggsSendMessageTool = defineTool('ziggs_send_message', {
 // Inbox read/ack are deliberately NOT here: the host owns the pull/watermark
 // cycle (InboxCatchUp on connect). A brain-side ack raced the host's and the
 // mandatory per-wake inbox poll fed the tool-operation echo loop (ZIG-759).
+//
+// list_grants IS here (ZIG-893): the hosted agent must always be able to answer
+// "what grants of mine do you hold?" across every rail — the 2026-07-20 incident
+// was a hosted agent with no grant-read tool telling its principal that lookup
+// doesn't exist. It reads operatorKey/agentId straight off the tool context.
 export const CLAUDE_SDK_TOOLS = [
     ziggsContextSnapshotTool,
     ziggsSendMessageTool,
+    listGrantsTool,
 ];

package/dist/index.d.ts

@@ -51,11 +51,8 @@ export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';
 export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
-export { ZiggsPayClient, createZiggsPayClient } from './server/ziggspay/ZiggsPayClient.js';
-export { ZiggsConnectClient, createZiggsConnectClient } from './server/ziggsconnect/ZiggsConnectClient.js';
-export { ZiggsContextClient } from './server/ziggscontext/ZiggsContextClient.js';
-export type { ZiggsContextClientOptions, ContextReachDescriptor, DelegateContextGrantParams, } from './server/ziggscontext/ZiggsContextClient.js';
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, } from './server/tools/index.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
+export { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export type { MemoryStore } from './memory/MemoryStore.js';

package/dist/index.js

@@ -44,16 +44,22 @@ export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';
 export { ProactiveTrigger } from './server/proactive/ProactiveTrigger.js';
-export { ZiggsPayClient, createZiggsPayClient } from './server/ziggspay/ZiggsPayClient.js';
-export { ZiggsConnectClient, createZiggsConnectClient } from './server/ziggsconnect/ZiggsConnectClient.js';
-export { ZiggsContextClient } from './server/ziggscontext/ZiggsContextClient.js';
+// ZIG-894 — the hand-rolled ZiggsPayClient / ZiggsConnectClient were deleted;
+// payment and connection tools now use @ziggs-ai/api-client's PaymentsClient /
+// ConnectionsClient, the same clients ziggs-mcp uses.
+// ZIG-869 — the hand-rolled ZiggsContextClient was deleted; context tools now
+// use the same @ziggs-ai/api-client clients as ziggs-mcp (GrantsClient /
+// ContextGrantsClient / ContextReadClient). Grant/reach types live there.
 // All agent tool bundles live under server/tools/ (tier1 = protocol grammar,
 // tier2 = opt-in HTTP capability bundles). Single home: server/tools/index.ts.
 export { 
 // Tier 1 — protocol grammar (framework-managed via taskTools).
 PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, dispatchProtocolOp, 
 // Tier 2 — opt-in capability bundles (spread into `tools:`).
-PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, } from './server/tools/index.js';
+PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './server/tools/index.js';
+// The always-on toolset for the hosted Claude cognition (ZIG-903 parity guard
+// reads this as part of the real SDK registry).
+export { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export { classifyIncomingEvent } from './context/classifyEnvelope.js';

package/dist/server/tools/index.d.ts

@@ -19,6 +19,10 @@ export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreeme
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
-export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
+export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
+export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/index.js

@@ -21,6 +21,16 @@ export { dispatchProtocolOp } from './tier1/protocolRunner.js';
 // ── Tier 2: capability bundles ──────────────────────────────────────────────
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
-export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+// ZIG-893: one grant lister across every rail (retires context_discover +
+// payment_list_grants). Always-available on the hosted agent — see CLAUDE_SDK_TOOLS.
+export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
+// ZIG-898: links (agreements with engagementKind 'link') — cross-org reach.
+export { LINK_TOOLS, requestLinkTool, createLinkInviteTool, claimLinkInviteTool, listLinksTool, revokeLinkTool, } from './tier2/linkTools.js';
+// ZIG-899: deliberate artifact recording (the model decides "record this").
+export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
+// ZIG-900 decision: open_conversation only — chat listing stays a context-rail
+// read (list_grants scopeKind=chat), no duplicate lister (ZIG-626 rule).
+export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/tier2/artifactTools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const recordArtifactTool: ToolDefinition;
+export declare const ARTIFACT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/artifactTools.js

@@ -0,0 +1,82 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { ArtifactsClient } from '@ziggs-ai/api-client';
+/**
+ * ZIG-899 — deliberate artifact recording on the SDK surface, same base name
+ * as ziggs-mcp's ziggs_record_artifact. Until now artifacts were written only
+ * as a host-side effect (recordReport / record-event); the model could not
+ * decide "this is a deliverable, record it" — which is exactly what the
+ * delegate protocol tells agents to do for heavy results. Rides
+ * ArtifactsClient.writeStrict (fail loudly, return the artifactId) — the same
+ * wire call as the MCP tool.
+ */
+function creds(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+/**
+ * ZIG-560 teaching carried over from the MCP tool: name the result slot on the
+ * success path so an agent finds the right move unaided — reworded to the SDK
+ * task grammar (task_update carries the terminal result on this surface).
+ */
+function reportingHint(contentType, taskId) {
+    if (contentType === 'result') {
+        return taskId
+            ? 'Recorded as a task-bound result artifact. Close the task by setting its terminal result with task_update.'
+            : 'Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with task_update.';
+    }
+    return 'Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with task_update — chat messages are conversation only.';
+}
+export const recordArtifactTool = defineTool('record_artifact', {
+    text: { type: 'string', required: true, description: 'Artifact body' },
+    visibility: {
+        type: 'string',
+        required: true,
+        enum: ['chat', 'agent-private'],
+        description: 'chat = visible to scope parties; agent-private = your eyes only',
+    },
+    chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
+    agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
+    taskId: {
+        type: 'string',
+        description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
+    },
+    content_type: { type: 'string', description: 'Default text; use result for a finished deliverable' },
+}, async (args, ctx) => {
+    const chatId = args['chatId'];
+    const agreementId = args['agreementId'];
+    if ((chatId && agreementId) || (!chatId && !agreementId)) {
+        throw new Error('Pass exactly one of chatId or agreementId');
+    }
+    const visibility = args['visibility'];
+    if (visibility !== 'chat' && visibility !== 'agent-private') {
+        throw new Error('visibility must be chat or agent-private');
+    }
+    const contentType = args['content_type'];
+    const taskId = args['taskId'];
+    const { operatorKey, agentId } = creds(ctx);
+    const { artifactId } = await new ArtifactsClient(operatorKey, agentId).writeStrict({
+        text: args['text'],
+        visibility,
+        chatId,
+        agreementId,
+        taskId,
+        content_type: contentType,
+    });
+    return {
+        ok: true,
+        artifactId,
+        visibility,
+        chatId,
+        agreementId,
+        taskId,
+        reportingHint: reportingHint(contentType, taskId),
+    };
+}, {
+    description: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+});
+export const ARTIFACT_TOOLS = [recordArtifactTool];

package/dist/server/tools/tier2/chatTools.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from '../../../tools/defineTool.js';
+export declare const openConversationTool: ToolDefinition;
+export declare const CHAT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/chatTools.js

@@ -0,0 +1,37 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { openConversation } from '@ziggs-ai/api-client';
+/**
+ * ZIG-900 — the decided chat surface for hosted agents: open_conversation
+ * only, same base name as MCP's ziggs_open_conversation. There is deliberately
+ * NO chat-listing tool on the SDK: agents read context only via held grants
+ * (ZIG-425) and chat membership auto-mints a chat grant (ZIG-428/426), so
+ * "what chats can I see" is already answered by list_grants scopeKind=chat —
+ * adding a lister would duplicate a context-family read (ZIG-626 rule).
+ */
+function creds(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    const agentId = ctx?.['agentId'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+export const openConversationTool = defineTool('open_conversation', {
+    participantId: {
+        type: 'string',
+        required: true,
+        description: 'User or agent id to converse with (from agent_search — do not guess ids)',
+    },
+}, async (args, ctx) => {
+    if (!args['participantId'])
+        throw new Error('participantId is required');
+    const { chatId } = await openConversation(args['participantId'], creds(ctx));
+    return {
+        chatId,
+        note: 'Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in list_grants scopeKind=chat for context reads.',
+    };
+}, {
+    description: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
+});
+export const CHAT_TOOLS = [openConversationTool];

package/dist/server/tools/tier2/connectionTools.d.ts

@@ -1,4 +1,5 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const connectionProxyTool: ToolDefinition;
 export declare const connectionListGrantsTool: ToolDefinition;
+export declare const requestConnectionTool: ToolDefinition;
 export declare const CONNECTION_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/connectionTools.js

@@ -1,13 +1,13 @@
 import { defineTool } from '../../../tools/defineTool.js';
-import { ZiggsConnectClient } from '../../ziggsconnect/ZiggsConnectClient.js';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
 function clientFor(ctx) {
     const operatorKey = ctx?.['operatorKey'];
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    return new ZiggsConnectClient({
-        operatorKey,
-        actAsAgentId: ctx?.['agentId'] || undefined,
-    });
+    // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the shared
+    // client defaults to HTTP_URL (api-client convention) when neither is set.
+    const baseUrl = process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined;
+    return new ConnectionsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
 }
 function rethrowWithContext(error, prefix) {
     const e = error;
@@ -57,7 +57,54 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', { c
         rethrowWithContext(e, 'Failed to list connection grants');
     }
 });
+export const requestConnectionTool = defineTool('request_connection', {
+    chatId: {
+        type: 'string',
+        required: true,
+        description: 'The chat you are working in — the consent card is opened there',
+    },
+    serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
+    tools: {
+        type: 'array',
+        items: { type: 'string' },
+        required: true,
+        description: "Tool names you want — become the grant's allowed_actions caveats",
+    },
+    reason: {
+        type: 'string',
+        description: 'Plain-language reason shown to the human deciding',
+    },
+}, async (args, ctx) => {
+    if (!args['chatId'])
+        throw new Error('chatId is required');
+    if (!args['serverUrl'])
+        throw new Error('serverUrl is required');
+    const tools = args['tools'];
+    if (!Array.isArray(tools) || tools.length === 0) {
+        throw new Error('tools must be a non-empty array of tool names');
+    }
+    try {
+        const result = await clientFor(ctx).requestMcpConnection({
+            chatId: args['chatId'],
+            serverUrl: args['serverUrl'],
+            tools: tools,
+            reason: args['reason'],
+        });
+        return {
+            ok: true,
+            ...result,
+            note: 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
+                'Once approved, the connection + grant appear in list_grants (scopeKind=connection) / connection_list_grants for connection_proxy.',
+        };
+    }
+    catch (e) {
+        rethrowWithContext(e, 'Connection request failed');
+    }
+}, {
+    description: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. On approval the server is connected (browser OAuth if needed) and you are granted the tools; use them via connection_proxy.',
+});
 export const CONNECTION_TOOLS = [
     connectionProxyTool,
     connectionListGrantsTool,
+    requestConnectionTool,
 ];

package/dist/server/tools/tier2/contextTools.d.ts

@@ -1,4 +1,6 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
-export declare const contextDiscoverTool: ToolDefinition;
+export declare const contextReadTool: ToolDefinition;
 export declare const contextDelegateTool: ToolDefinition;
-export declare const CONTEXT_TOOLS: readonly [ToolDefinition, ToolDefinition];
+export declare const contextExpandReachTool: ToolDefinition;
+export declare const contextDiscoverGrantableTool: ToolDefinition;
+export declare const CONTEXT_TOOLS: readonly [ToolDefinition, ToolDefinition, ToolDefinition, ToolDefinition];