@ziggs-ai/agent-sdk 0.12.0 → 0.14.0

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/runtime/mandateDeclaration.d.ts

@@ -0,0 +1,9 @@
+import type { ToolManager } from '../tools/ToolManager.js';
+/**
+ * Add the wake's own mandate to a tool call that declares one and left it blank.
+ *
+ * Returns the args unchanged whenever there is nothing to say: the tool takes no
+ * declaration, the model already made one, or this wake is not running inside a
+ * job at all.
+ */
+export declare function withDeclaredMandate(args: Record<string, unknown>, toolName: string | null | undefined, toolManager: ToolManager | undefined, activeAgreementId: string | null | undefined): Record<string, unknown>;

package/dist/runtime/mandateDeclaration.js

@@ -0,0 +1,62 @@
+/**
+ * Fill in the job an agent is working inside, so it does not have to.
+ *
+ * The consent gate excuses an agreement an agent forms INSIDE a job its human
+ * already approved, and it verifies the claim server-side. What was missing was
+ * the claim itself: nothing on the agent surface said "I am doing this as part
+ * of job X", so every engagement an agent formed arrived as an outsider and
+ * waited on a human — including buying the help the job it was hired for needs.
+ *
+ * The declaration is made at the CALLER, never resolved on the server: the
+ * agreements module must not read the tasks module, and a guessed mandate is a
+ * false claim the termination cascade would act on destructively. Here the fact
+ * is free — the runtime already knows which task this wake is executing and
+ * which agreement that task runs under, which is exactly the answer.
+ *
+ * The model can still name a job itself (and does, when it is working on
+ * something other than its assigned task). An explicit value is never
+ * overwritten, including an explicit empty string, which reads as "this belongs
+ * to no job" — the difference between saying nothing and saying none.
+ */
+/**
+ * The parameter a tool uses to carry the declaration.
+ *
+ * Two names, because the doors differ and each name is true at its own door: on
+ * a tool that CREATES an agreement the job becomes that row's parent, so the
+ * field is the parent id; on a tool that claims a row somebody else posted
+ * nothing is re-parented — the lineage stays with the publisher — and the job is
+ * only an authority. Listed together here so the runtime has one place that
+ * knows both, rather than a name test at each call site.
+ */
+const MANDATE_PARAM_NAMES = ['mandateAgreementId', 'parentAgreementId'];
+/** The mandate parameter this tool declares, if it declares one. */
+function mandateParamOf(toolName, toolManager) {
+    if (!toolName)
+        return null;
+    const schema = toolManager?.getTool?.(toolName)?.schema;
+    const properties = schema?.function?.parameters?.properties;
+    if (!properties)
+        return null;
+    for (const name of MANDATE_PARAM_NAMES) {
+        if (Object.prototype.hasOwnProperty.call(properties, name))
+            return name;
+    }
+    return null;
+}
+/**
+ * Add the wake's own mandate to a tool call that declares one and left it blank.
+ *
+ * Returns the args unchanged whenever there is nothing to say: the tool takes no
+ * declaration, the model already made one, or this wake is not running inside a
+ * job at all.
+ */
+export function withDeclaredMandate(args, toolName, toolManager, activeAgreementId) {
+    if (!activeAgreementId)
+        return args;
+    const param = mandateParamOf(toolName, toolManager);
+    if (!param)
+        return args;
+    if (args[param] !== undefined)
+        return args;
+    return { ...args, [param]: activeAgreementId };
+}

package/dist/runtime/runTurn.js

@@ -1,6 +1,7 @@
 import { outcomeFromActionResult } from './buildOutcome.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { safeParseJSON } from '../utils/jsonExtractor.js';
+import { withDeclaredMandate } from './mandateDeclaration.js';
 const MAX_TOOL_LOOP_ITERS = 20;
 const MAX_MSG_CHARS = 3500;
 /**
@@ -260,6 +261,9 @@ export async function runTurn(input) {
                     args = JSON.parse(tc.function.arguments || '{}');
                 }
                 catch { }
+                // Say which job this is part of, when the tool asks and the model did
+                // not. The runtime knows; the model would have to be told.
+                args = withDeclaredMandate(args, toolName, toolManager, ctx.activeAgreementId);
                 const decision = { action: matchingAction, tool: toolName, args };
                 const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
                 toolCallResults.push({ tc, matchingAction, result, args, actionDef });
@@ -311,6 +315,10 @@ export async function runTurn(input) {
             const decision = parsed.decision;
             const chosenAction = decision.action;
             const actionDef = actions[chosenAction];
+            // Same mandate declaration as the tool-call path above. Both routes reach
+            // the same tools, so filling it on only one would make the excuse depend on
+            // which shape the model happened to answer in.
+            decision.args = withDeclaredMandate((decision.args ?? {}), actionDef?.tool, toolManager, ctx.activeAgreementId);
             if (decision.thought)
                 await emitThought(decision.thought);
             // 2-call streaming: if this is a respond action (has receiverId, no bound tool),

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

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, 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);
@@ -25,15 +25,22 @@ export declare class AgreementService {
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
      */
-    claim(agreementId: string): Promise<{
+    claim(agreementId: string, opts?: ClaimOptions): Promise<{
         agreement: Agreement;
         kind: ClaimedKind;
     }>;
     /**
-     * a link proposal is an agreement (engagementKind 'link') to one
-     * agent; the target owner approves. Folds the old request_link tool.
+     * Connect with the person an agent answers for.
+     *
+     * `to` is an email or an agent id. A link is with the PERSON either way: an id
+     * is only a way to find its owner, and one that answers to an org is refused.
+     *
+     * The reply says only that the invitation went. Handing back the agreement for
+     * an id target while an address target got a bare acknowledgement told the
+     * caller more about one kind of target than the other, which made the id form
+     * a way to check who has an account.
      */
-    requestLink(providerId: string, description?: string): Promise<Agreement>;
+    requestLink(to: string, description?: string): Promise<CreateLinkResult>;
     counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement>;
     getStatus(agreementId: string): Promise<unknown | null>;
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
@@ -46,14 +53,11 @@ export declare class AgreementService {
     mine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(agreementId: string): Promise<Agreement | null>;
     /**
-     * Create a trust link — direct to one agent, or an open invite. Work
+     * Connect with someone — by email, by agent id, or with a share link. Work
      * agreements are created by `propose` / the marketplace claim routes, which
      * run the term normalisation and consent gates this rail never had.
      */
-    createLink(body: CreateLinkBody): Promise<{
-        ok: boolean;
-        agreement: Agreement;
-    }>;
+    createLink(body: CreateLinkBody): Promise<CreateLinkResult>;
     revoke(agreementId: string): Promise<{
         ok: boolean;
         agreement: Agreement;
@@ -66,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) {
@@ -43,16 +43,22 @@ export class AgreementService {
      * the shared flow; `kind` is the api-client ClaimedKind so this signature
      * can't drift from the flow again (a 'hand-off' addition broke the build).
      */
-    claim(agreementId) {
-        return claimOpenAgreement(agreementId, this.creds);
+    claim(agreementId, opts = {}) {
+        return claimOpenAgreement(agreementId, this.creds, opts);
     }
     /**
-     * a link proposal is an agreement (engagementKind 'link') to one
-     * agent; the target owner approves. Folds the old request_link tool.
+     * Connect with the person an agent answers for.
+     *
+     * `to` is an email or an agent id. A link is with the PERSON either way: an id
+     * is only a way to find its owner, and one that answers to an org is refused.
+     *
+     * The reply says only that the invitation went. Handing back the agreement for
+     * an id target while an address target got a bare acknowledgement told the
+     * caller more about one kind of target than the other, which made the id form
+     * a way to check who has an account.
      */
-    async requestLink(providerId, description) {
-        const { agreement } = await createLink({ targetAgentId: providerId, ...(description ? { description } : {}) }, this.creds);
-        return agreement;
+    async requestLink(to, description) {
+        return createLink({ to, ...(description ? { description } : {}) }, this.creds);
     }
     counter(agreementId, counter) {
         return counterAgreement(agreementId, counter || {}, this.creds);
@@ -76,7 +82,7 @@ export class AgreementService {
         return getAgreement(agreementId, this.creds);
     }
     /**
-     * Create a trust link — direct to one agent, or an open invite. Work
+     * Connect with someone — by email, by agent id, or with a share link. Work
      * agreements are created by `propose` / the marketplace claim routes, which
      * run the term normalisation and consent gates this rail never had.
      */
@@ -101,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/proactive/ProactiveTrigger.d.ts

@@ -5,7 +5,13 @@ interface TickContext {
     marketplace: {
         publishOffer: (payload: PublishOfferPayload) => Promise<unknown>;
         pullOffers: (options?: PullOffersOptions) => Promise<unknown[]>;
-        claimOffer: (agreementId: string) => Promise<unknown>;
+        /**
+         * Claim any open broadcast. One verb: the backend routes on which side of
+         * the row is open, and a caller cannot work that out for itself — reading
+         * the agreement first is party-scoped, and a claimer is by definition not
+         * yet a party.
+         */
+        claimAgreement: (agreementId: string) => Promise<unknown>;
     };
 }
 interface ProactiveTriggerOptions {

package/dist/server/proactive/ProactiveTrigger.js

@@ -1,4 +1,4 @@
-import { publishOffer, pullOffers, claimOffer } from '@ziggs-ai/api-client';
+import { publishOffer, pullOffers, claimOpenAgreement } from '@ziggs-ai/api-client';
 import { runtimeLog } from '../../shared/runtimeLog.js';
 export class ProactiveTrigger {
     interval;
@@ -64,7 +64,7 @@ export class ProactiveTrigger {
             marketplace: {
                 publishOffer: (payload) => publishOffer(payload, creds),
                 pullOffers: (options) => pullOffers(options, creds),
-                claimOffer: (agreementId) => claimOffer(agreementId, creds),
+                claimAgreement: (agreementId) => claimOpenAgreement(agreementId, creds),
             },
         };
     }

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

@@ -23,7 +23,7 @@ export { PAYMENT_TOOLS, paymentBalanceTool } 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, linkCreateInviteTool, linkListTool, } from './tier2/linkTools.js';
+export { LINK_TOOLS, linkProposeTool, linkListTool, } from './tier2/linkTools.js';
 export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
 export { MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, } from './tier2/mcpConnectionTools.js';
 export { CHAT_TOOLS, openConversationTool } from './tier2/chatTools.js';

package/dist/server/tools/index.js

@@ -30,7 +30,7 @@ export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
 // links (agreements with engagementKind 'link') — cross-org reach.
 ///1022: the rail is two tools; propose/claim/revoke ride the
 // agreement grammar.
-export { LINK_TOOLS, linkCreateInviteTool, linkListTool, } from './tier2/linkTools.js';
+export { LINK_TOOLS, linkProposeTool, linkListTool, } from './tier2/linkTools.js';
 // deliberate artifact recording (the model decides "record this").
 export { ARTIFACT_TOOLS, recordArtifactTool } from './tier2/artifactTools.js';
 export { MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, } from './tier2/mcpConnectionTools.js';

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

@@ -1,4 +1,4 @@
-import { isBroadcastTarget, } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, partyActorIds, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
 // the link-summary rule lives in AgreementClient, at the point the
 // document is parsed. Every verb here inherits it through the client instead of
@@ -66,7 +66,16 @@ cachedAgreements) {
             // the one claim verb — request, standing offer, or link invite.
             if (!payload.agreementId)
                 throw new Error('agreement-claim requires `agreementId`');
-            return await agreementService.claim(payload.agreementId);
+            // The job this claim is part of, when the caller named one
+            // (the runtime fills it from the task being executed). It authorizes the
+            // claim; it does not re-parent the row, which stays in the publisher's
+            // tree.
+            const declaredMandate = payload.mandateAgreementId;
+            return await agreementService.claim(payload.agreementId, {
+                ...(typeof declaredMandate === 'string' && declaredMandate
+                    ? { mandateAgreementId: declaredMandate }
+                    : {}),
+            });
         }
         case 'agreement-counter-proposal':
             if (!payload.agreementId)
@@ -217,7 +226,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
     // no chat, no money; the target owner approves. Folds the old request_link.
     if (payload.engagementKind === 'link') {
         if (isBroadcast) {
-            throw new Error('A broadcast link is an invite — use link_create_invite instead; propose links to one agent id.');
+            throw new Error('A broadcast link is an invite — use link_propose with no target instead; it returns a share link.');
         }
         return services.agreementService.requestLink(payload.proposedTo, payload.description);
     }
@@ -283,13 +292,10 @@ async function agreementsInChat(services, chatId, cachedAgreements) {
     }
 }
 function agIsProvider(a, agentId) {
-    const p = a.parties ?? {};
-    return p['provider'] === agentId || p['providerAgent'] === agentId || a['providerId'] === agentId;
+    return a.parties?.provider?.actor === agentId || a['providerId'] === agentId;
 }
 function agIsParty(a, agentId) {
-    const p = a.parties ?? {};
-    return ['provider', 'providerAgent', 'payer', 'proposedTo', 'creator', 'creatorAgent']
-        .some((k) => p[k] === agentId);
+    return partyActorIds(a.parties).includes(agentId);
 }
 function agActive(a) {
     return !a.status || !TERMINAL_STATUS.has(String(a.status));

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

@@ -43,10 +43,15 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, 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.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose (or link_create_invite when you lack the agent id). engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
+export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, 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.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string' }, handlerFor('agreement_propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
 export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, payerId: 'string', 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.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, handlerFor('agreement_subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
 export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement_respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (requests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
-export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (request / offer / link invite id)' } }, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
+export const agreementClaimTool = defineTool('agreement_claim', {
+    agreementId: { type: 'string', required: true, description: 'The open agreement to claim (request / offer / link invite id)' },
+    // The job this claim is part of. Filled in from the task this wake is
+    // executing when the agent does not name one itself.
+    mandateAgreementId: { type: 'string', description: 'The active agreement whose work this claim is part of — the job you are doing. Claiming for a job your human already approved needs no second approval from them, but you have to name the job: the server checks you are a party to it, and a wrong name simply earns nothing. Leave it out when the claim belongs to no job.' },
+}, handlerFor('agreement_claim'), { description: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim, activation is instant, no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed.' });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
@@ -60,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/server/tools/tier2/linkTools.d.ts

@@ -1,4 +1,4 @@
 import type { ToolDefinition } from '../../../tools/defineTool.js';
-export declare const linkCreateInviteTool: ToolDefinition;
+export declare const linkProposeTool: ToolDefinition;
 export declare const linkListTool: ToolDefinition;
 export declare const LINK_TOOLS: ToolDefinition[];

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

@@ -1,13 +1,15 @@
-import { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, } from '@ziggs-ai/api-client';
+import { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
-// links are agreements with engagementKind 'link':
-// bilateral agent-to-agent trust that gives any unpublished agent cross-org
-// reach. Defined once in api-client's shared capability layer (including the
-// linkSummary shaping); this file only adapts them onto the SDK.
+// links are agreements with engagementKind 'link': bilateral trust between two
+// PEOPLE that gives either side reach to the other. Defined once in api-client's
+// shared capability layer (including the linkSummary shaping); this file only
+// adapts them onto the SDK.
 //
-///1022 shrank the rail to two tools. The agreement verbs carry the
-// rest: request a direct link with agreement_propose (engagementKind 'link'),
-// claim an invite with agreement_claim, end a link with agreement_revoke.
-export const linkCreateInviteTool = toolFromCapability(createLinkInviteCapability);
+// Two tools. There were three: `link_create_invite` was `link_propose` with a
+// different way of naming the other side, so a caller had to choose between them
+// before knowing which applied. One verb takes an email, an agent id, or
+// nothing. The agreement verbs carry the rest: claim an invite with
+// agreement_claim, end a link with agreement_revoke.
+export const linkProposeTool = toolFromCapability(proposeLinkCapability);
 export const linkListTool = toolFromCapability(listLinksCapability);
 export const LINK_TOOLS = toolsFromCapabilities(LINK_CAPABILITIES);

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 {};