@ziggs-ai/agent-sdk 0.13.0 → 0.14.0

package/dist/agent/claudeCognition.js

@@ -151,6 +151,18 @@ function renderEventLines(event, lines) {
                 lines.push(`Agreement: ${agreementId}`);
             }
         }
+        // The other side of the same policy: a message this agent sent to a
+        // published agent landed and was NOT rung through. Nothing is wrong and
+        // nothing is lost, so this must not read as a refusal — but without it the
+        // sender waits on a reply that is never coming and its rational next move
+        // is to send again.
+        if (reason === 'contact_policy_withheld') {
+            lines.push('Your message was delivered and is readable, but the agent you wrote ' +
+                'to is not woken for it: its listing is claim-first, so it starts ' +
+                'work once you claim the listing. Do not resend — claim the listing ' +
+                '(ziggs_marketplace_view to find it, then ziggs_agreement_claim), or ' +
+                'wait if somebody else is claiming on your behalf.');
+        }
     }
     if (typeof event?.agreementId === 'string' && event.agreementId) {
         lines.push(`Agreement: ${event.agreementId}`);

package/dist/agent/claudeSdkTools.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { laneFromToolContext } from '../tools/toolCreds.js';
 import { listTasks } from '@ziggs-ai/api-client';
 import { defineTool } from '../tools/defineTool.js';
 import { listGrantsTool } from '../server/tools/tier2/grantsTools.js';
@@ -177,7 +178,10 @@ export const listTasksTool = defineTool('task_list', {
     const createdBy = args.createdByMe ? c.agentId : undefined;
     // the lane fences this to the engagement's tasks. Without it the
     // list is every task the agent's key can reach, across all its customers.
-    const laneId = c.chatId || c.sessionId || undefined;
+    // One reader for the lane, shared with the capability adapter and with
+    // hand-written tools — three copies of `chatId || sessionId` is how one of
+    // them ends up not claiming the reach the fence exists to grant.
+    const laneId = laneFromToolContext(c);
     return listTasks({
         state: args.state,
         cursor: args.cursor,

package/dist/index.d.ts

@@ -53,6 +53,7 @@ export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
+export { credsFromToolContext, laneFromToolContext } from './tools/toolCreds.js';
 export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
 export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 export type { AgentNeed, ConnectionNeed } from './tools/needs.js';

package/dist/index.js

@@ -55,6 +55,7 @@ export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
+export { credsFromToolContext, laneFromToolContext } from './tools/toolCreds.js';
 // An agent declares the access it cannot work without, and the declaration
 // produces the tools for it.
 export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';

package/dist/pricing/fleetDefaults.d.ts

@@ -8,7 +8,6 @@ export declare const TIER_PRICE_CENTS: Record<FleetPricingTier, number>;
 export declare function resolveFleetTier(agentId: string): FleetPricingTier | null;
 export declare function isFirstPartyFleetAgent(agentId: string): boolean;
 export declare function tierPriceCents(tier: FleetPricingTier): number;
-export declare function isZiggsOrchestrator(agentId: string): boolean;
 export declare function isFreeAllowlistedExecutor(executorId: string, description?: string | null): boolean;
 export declare function resolveDefaultPriceCentsForExecutor(executorId: string, description?: string | null): number | null;
 export interface ProtocolPricingPayload {

package/dist/pricing/fleetDefaults.js

@@ -12,7 +12,6 @@ export const TIER_PRICE_CENTS = {
     C: 1500, // 15 ZIG / job (orchestrator, charged once at top)
     D: 100, // 1 ZIG / call (hand-written demo agents)
 };
-const ZIGGS_ORCHESTRATOR_IDS = new Set(['ziggs-agent']);
 const PING_DESCRIPTION_PATTERN = /\b(ping|health\s*check|healthcheck|liveness|readiness|heartbeat)\b/i;
 const TRIVIAL_LOOKUP_DESCRIPTION_PATTERN = /\b(what\s+time|current\s+time|local\s+time|world\s+clock|timezone|time\s+zone|weather|forecast|temperature|uv\s+index)\b/i;
 export function resolveFleetTier(agentId) {
@@ -26,9 +25,6 @@ export function isFirstPartyFleetAgent(agentId) {
 export function tierPriceCents(tier) {
     return TIER_PRICE_CENTS[tier];
 }
-export function isZiggsOrchestrator(agentId) {
-    return ZIGGS_ORCHESTRATOR_IDS.has(agentId);
-}
 export function isFreeAllowlistedExecutor(executorId, description) {
     if (!executorId)
         return false;
@@ -82,14 +78,13 @@ export function applyFleetAgreementPricing(operation, payload, actingAgentId) {
     }
     const proposedTo = next.proposedTo != null ? String(next.proposedTo) : '';
     const providerId = next.providerId != null ? String(next.providerId) : '';
-    // Ziggs scope proposal to human user — 15 ZIG once at top.
-    if (isZiggsOrchestrator(actingAgentId) &&
-        proposedTo &&
-        !isFirstPartyFleetAgent(proposedTo)) {
-        next.price = TIER_PRICE_CENTS.C;
-        return next;
-    }
-    // Tier C orchestrator proposing scope to a user (non-ziggs fleet orchestrators).
+    // A tier C orchestrator proposing scope to a user — 15 ZIG once at top.
+    //
+    // The ziggs delegate used to have its own branch above this one, keyed on a
+    // hardcoded id. It asked the same question with the same answer — that agent
+    // is tier C, so this line already priced it. A second way of asking the tier
+    // question the tier had already answered, which is the same shape that was
+    // removed from the backend copy.
     const actingTier = resolveFleetTier(actingAgentId);
     if (actingTier === 'C' && proposedTo && !isFirstPartyFleetAgent(proposedTo)) {
         next.price = TIER_PRICE_CENTS.C;

package/dist/runtime/kickoff.d.ts

@@ -11,15 +11,28 @@ export declare function buildKickoffState(initial: string): ThinkingState;
 export declare function buildClaimKickoffState(initial: string): ThinkingState;
 /**
  * Agreement-kickoff defaults. For every state whose transitions do not already
- * match the corresponding probe, append a transition to the injected kickoff
- * state. Appended LAST so any user transition on the same outcome always wins
- * (first match wins in AgentMachine._evaluateTransitions). Returns a NEW
- * workflow — input states are not mutated.
+ * handle the corresponding probe, add a transition to the injected kickoff
+ * state. Returns a NEW workflow — input states are not mutated.
  *
  * Two kickoffs:
  *  - `kickingOff` — proposer-side approval → task_create
  *  - `claimKickingOff` — store-claim provider wake → chat_open + greet
  * Direct-proposal counterparties (lifecycle approve, !proposedByMe, no
  * fromClaimWake) still never auto-kickoff.
+ *
+ * **They are ordered differently on purpose** (first match wins in
+ * AgentMachine._evaluateTransitions):
+ *
+ *  - `kickingOff` is appended LAST. It fires on an approval of a proposal THIS
+ *    agent made, which the author was already expecting — whatever route they
+ *    wrote for it should keep winning.
+ *  - `claimKickingOff` is inserted FIRST. It fires on a wake the author never
+ *    wrote a route for, and it has to beat the unconditional fallthrough an
+ *    `idle` state uses to reach its listening loop — otherwise the claim is
+ *    swallowed into the idle loop and the buyer is never greeted. Going first
+ *    is safe because its `when` is narrow: only a `fromClaimWake` approve
+ *    matches, so nothing else is shadowed. An author who wants the claim for
+ *    themselves keys on `fromClaimWake`, which suppresses the injection
+ *    outright (stateHandlesClaimKickoff).
  */
 export declare function injectKickoffDefault(workflow: Workflow): Workflow;

package/dist/runtime/kickoff.js

@@ -25,6 +25,18 @@ const PROBE_CLAIM_APPROVE = {
     proposedByMe: false,
     fromClaimWake: true,
 };
+/**
+ * A bare counterparty approve — someone approved a proposal we did not make,
+ * with no store claim behind it. Used as a NEGATIVE probe: a transition that
+ * matches this as well as PROBE_CLAIM_APPROVE is a generic proposal-resolved
+ * route, not a deliberate claim handler, so it does not suppress injection.
+ */
+const PROBE_BARE_APPROVE = {
+    kind: 'proposal-resolved',
+    action: 'approve',
+    proposal: { agreementId: '__bare_approve_probe__' },
+    proposedByMe: false,
+};
 const KICKOFF_TRANSITION = {
     to: KICKOFF_STATE,
     when: (o, ctx) => o.kind === 'proposal-resolved' &&
@@ -69,17 +81,32 @@ function stateHandlesProposerApproval(state) {
         }
     });
 }
+function matches(t, probe) {
+    if (!t.when)
+        return false;
+    try {
+        return !!t.when(probe, PROBE_CTX);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A state handles the claim kickoff itself only when it says so EXPLICITLY —
+ * a transition that fires for a store-claim wake and does NOT also fire for a
+ * bare counterparty approve. In practice that means keying on `fromClaimWake`.
+ *
+ * Two weaker rules read as "handled" when nothing was. A when-less fallthrough
+ * counted, so a state shaped `idle → listening` never got the transition
+ * injected and routed every claim into its idle loop; and a `when: o => o.kind
+ * === 'proposal-resolved'` route counted too, because the claim probe is also a
+ * proposal-resolved/approve. Neither author had written anything about claims.
+ * Requiring the negative probe to MISS is what tells a deliberate claim handler
+ * apart from a generic one, and the unconditional case is safe to inject over
+ * because the claim transition goes in FIRST — see injectKickoffDefault.
+ */
 function stateHandlesClaimKickoff(state) {
-    return state.transitions.some(t => {
-        if (!t.when)
-            return true;
-        try {
-            return !!t.when(PROBE_CLAIM_APPROVE, PROBE_CTX);
-        }
-        catch {
-            return false;
-        }
-    });
+    return state.transitions.some(t => matches(t, PROBE_CLAIM_APPROVE) && !matches(t, PROBE_BARE_APPROVE));
 }
 export function buildKickoffState(initial) {
     const dflt = thinkingDefaults({ initial });
@@ -161,16 +188,29 @@ export function buildClaimKickoffState(initial) {
 }
 /**
  * Agreement-kickoff defaults. For every state whose transitions do not already
- * match the corresponding probe, append a transition to the injected kickoff
- * state. Appended LAST so any user transition on the same outcome always wins
- * (first match wins in AgentMachine._evaluateTransitions). Returns a NEW
- * workflow — input states are not mutated.
+ * handle the corresponding probe, add a transition to the injected kickoff
+ * state. Returns a NEW workflow — input states are not mutated.
  *
  * Two kickoffs:
  *  - `kickingOff` — proposer-side approval → task_create
  *  - `claimKickingOff` — store-claim provider wake → chat_open + greet
  * Direct-proposal counterparties (lifecycle approve, !proposedByMe, no
  * fromClaimWake) still never auto-kickoff.
+ *
+ * **They are ordered differently on purpose** (first match wins in
+ * AgentMachine._evaluateTransitions):
+ *
+ *  - `kickingOff` is appended LAST. It fires on an approval of a proposal THIS
+ *    agent made, which the author was already expecting — whatever route they
+ *    wrote for it should keep winning.
+ *  - `claimKickingOff` is inserted FIRST. It fires on a wake the author never
+ *    wrote a route for, and it has to beat the unconditional fallthrough an
+ *    `idle` state uses to reach its listening loop — otherwise the claim is
+ *    swallowed into the idle loop and the buyer is never greeted. Going first
+ *    is safe because its `when` is narrow: only a `fromClaimWake` approve
+ *    matches, so nothing else is shadowed. An author who wants the claim for
+ *    themselves keys on `fromClaimWake`, which suppresses the injection
+ *    outright (stateHandlesClaimKickoff).
  */
 export function injectKickoffDefault(workflow) {
     if (workflow.states[KICKOFF_STATE]) {
@@ -189,7 +229,7 @@ export function injectKickoffDefault(workflow) {
             injectedProposer = true;
         }
         if (!stateHandlesClaimKickoff(state)) {
-            transitions.push(CLAIM_KICKOFF_TRANSITION);
+            transitions.unshift(CLAIM_KICKOFF_TRANSITION);
             injectedClaim = true;
         }
         states[name] =

package/dist/server/agreements/AgreementService.d.ts

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType, type UserRole } from '@ziggs-ai/api-client';
+import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType } from '@ziggs-ai/api-client';
 export declare class AgreementService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -70,6 +70,4 @@ export declare class AgreementService {
     getChats(agreementId: string): Promise<unknown[]>;
     linkArtifact(agreementId: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown | null>;
     getArtifacts(agreementId: string): Promise<unknown[]>;
-    linkUser(agreementId: string, userId: string, role: UserRole): Promise<unknown | null>;
-    getUsers(agreementId: string): Promise<unknown[]>;
 }

package/dist/server/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -107,10 +107,4 @@ export class AgreementService {
     getArtifacts(agreementId) {
         return getArtifactsForAgreement(agreementId, this.creds);
     }
-    linkUser(agreementId, userId, role) {
-        return linkUserToAgreement(agreementId, userId, role, this.creds);
-    }
-    getUsers(agreementId) {
-        return getUsersForAgreement(agreementId, this.creds);
-    }
 }

package/dist/server/inboxLoop.js

@@ -8,6 +8,20 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
+/**
+ * Standing proposals share the merged inbox visibility model with deliveries,
+ * but older envelopes predate an explicit assignee stamp. Prefer the server's
+ * role-to-actor assignment. On an older server, wake only for an agent-keyed
+ * approval/responder slot — withholding a wake is safer than waking every
+ * sibling merely because they share an org principal.
+ */
+function proposalIsMine(proposal, ownAgentId) {
+    if (proposal.assignedAgentId !== undefined) {
+        return proposal.assignedAgentId === ownAgentId;
+    }
+    return (proposal.pendingApprovalPartyIds?.includes(ownAgentId) === true ||
+        proposal.proposedTo === ownAgentId);
+}
 /**
  * Read the messages behind one chat's deliveries and hand them to the host.
  *
@@ -203,6 +217,11 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     // Pending decisions are standing state, not deliveries: they keep appearing
     // until answered, so dedup them the same way tasks are deduped.
     for (const proposal of envelope.proposalsAwaitingMe) {
+        // A proposal may be visible because this agent shares the accountable
+        // principal's mailbox. Only the role-designated side actor wakes; ambient
+        // sibling proposals remain available as context without creating a lane.
+        if (!proposalIsMine(proposal, deps.ownAgentId))
+            continue;
         const key = `proposal:${proposal.agreementId}`;
         if (deps.seen.has(key))
             continue;

package/dist/server/tools/tier1/protocolTools.js

@@ -65,7 +65,7 @@ export const taskSetResultTool = defineTool('task_set_result', {
 export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_get'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
-export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
+export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement_fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked and it cannot be reopened. Linked chats remain independent rooms governed by their own grants. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
 // `status` names its four values here because nothing else does: the backend is
 // the only place the vocabulary was written down, and it now rejects anything
 // outside it. Every reader (the chat step badge, the SDK's own plan formatter)

package/dist/tools/capabilityAdapter.js

@@ -1,4 +1,5 @@
 import { defineTool } from './defineTool.js';
+import { laneFromToolContext } from './toolCreds.js';
 /**
  * the SDK surface adapter for shared capability definitions
  * (api-client `capabilities/`). One capability (schema + handler + guidance)
@@ -10,13 +11,15 @@ export function toolFromCapability(cap) {
     return defineTool(cap.names.sdk, cap.params, async (args, ctx) => {
         const operatorKey = ctx?.['operatorKey'];
         const agentId = ctx?.['agentId'];
-        // the lane was already threaded to this exact point by
-        //'s shared executor (`chatId: effect.sessionId` in
-        // executeToolWithSideEffects); it just was not used to narrow anything.
-        // Reading it here makes the fence brain-agnostic by construction: the
-        // Claude brain and the FSM brain both arrive through this adapter.
-        const laneId = ctx?.['chatId'] ||
-            ctx?.['sessionId'];
+        // The lane the wake is running in was already threaded to this exact
+        // point by the shared executor (`chatId: effect.sessionId` in
+        // executeToolWithSideEffects). `laneFromToolContext` is the one reader
+        // for it, which makes the fence brain-agnostic by construction — the
+        // Claude brain, the FSM brain and hand-written tools all claim the same
+        // lane instead of each author remembering to. A capability may run
+        // without an agent id (`needsAgentId: false`), which is why this builds
+        // the creds itself rather than calling `credsFromToolContext`.
+        const laneId = laneFromToolContext(ctx);
         if (!operatorKey)
             throw new Error('operatorKey missing from tool context');
         if (cap.needsAgentId && !agentId)

package/dist/tools/toolCreds.d.ts

@@ -0,0 +1,37 @@
+/**
+ * toolCreds.ts — the credentials a tool acts under, read off its own context.
+ *
+ * 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
+ * (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
+ * SILENTLY: enumerations come back short rather than refused.
+ *
+ * Measured on a five-node graph run: a coordinator asking which tasks it had
+ * created saw 0 of 5 with no lane and 5 of 5 with its own lane declared. The
+ * `task_list({ createdByMe: true })` convergence check that `lab-hirer`'s prompt
+ * recommends would therefore answer "nothing yet" and rebuild the whole graph,
+ * billing every worker twice.
+ *
+ * So: one reader, used by every tool, rather than a field each author has to
+ * remember. Omitting the lane can only narrow reach, never widen it, which is
+ * why forgetting it never fails loudly.
+ */
+import type { Creds } from '@ziggs-ai/api-client';
+/** The loose bag `defineTool` hands a handler. */
+type ToolContext = Record<string, unknown> | undefined | null;
+/**
+ * The wake's lane, as the backend's `X-Ziggs-Lane` expects it: a chat id, or
+ * `agrn-<agreementId>` for an agreement lane. Undefined when the tool is
+ * running outside any lane (a bootstrap sweep, a test), which the fence reads
+ * as "own org only".
+ */
+export declare function laneFromToolContext(ctx: ToolContext): string | undefined;
+/**
+ * The creds a tool should act under. Throws when the context is missing what a
+ * call needs, rather than building something that 401s later somewhere else.
+ */
+export declare function credsFromToolContext(ctx: ToolContext, toolName?: string): Creds;
+export {};

package/dist/tools/toolCreds.js

@@ -0,0 +1,49 @@
+/**
+ * toolCreds.ts — the credentials a tool acts under, read off its own context.
+ *
+ * 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
+ * (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
+ * SILENTLY: enumerations come back short rather than refused.
+ *
+ * Measured on a five-node graph run: a coordinator asking which tasks it had
+ * created saw 0 of 5 with no lane and 5 of 5 with its own lane declared. The
+ * `task_list({ createdByMe: true })` convergence check that `lab-hirer`'s prompt
+ * recommends would therefore answer "nothing yet" and rebuild the whole graph,
+ * billing every worker twice.
+ *
+ * So: one reader, used by every tool, rather than a field each author has to
+ * remember. Omitting the lane can only narrow reach, never widen it, which is
+ * why forgetting it never fails loudly.
+ */
+const str = (ctx, key) => {
+    const value = ctx?.[key];
+    return typeof value === 'string' && value.trim() ? value : undefined;
+};
+/**
+ * The wake's lane, as the backend's `X-Ziggs-Lane` expects it: a chat id, or
+ * `agrn-<agreementId>` for an agreement lane. Undefined when the tool is
+ * running outside any lane (a bootstrap sweep, a test), which the fence reads
+ * as "own org only".
+ */
+export function laneFromToolContext(ctx) {
+    return str(ctx, 'chatId') ?? str(ctx, 'sessionId');
+}
+/**
+ * The creds a tool should act under. Throws when the context is missing what a
+ * call needs, rather than building something that 401s later somewhere else.
+ */
+export function credsFromToolContext(ctx, toolName) {
+    const where = toolName ? `${toolName}: ` : '';
+    const operatorKey = str(ctx, 'operatorKey');
+    if (!operatorKey)
+        throw new Error(`${where}operatorKey missing from tool context`);
+    const agentId = str(ctx, 'agentId');
+    if (!agentId)
+        throw new Error(`${where}agentId missing from tool context`);
+    const laneId = laneFromToolContext(ctx);
+    return { operatorKey, agentId, ...(laneId ? { laneId } : {}) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.13.0",
+  "version": "0.14.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.12.0",
+    "@ziggs-ai/api-client": "0.13.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",