@ziggs-ai/api-client 0.8.0 → 0.9.1

package/README.md

@@ -97,6 +97,16 @@ await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
 
 Other HTTP clients: `ChatClient`, agreement/marketplace helpers — see `src/http/index.ts`.
 
+### Persona wire shapes (ZIG-1137)
+
+Cross-org inbox and chat payloads mask counterparties behind presentation faces:
+
+- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org — not `requesterAgentId`.
+- Message/roster rows may carry `presentation` (`ref`, `persona`, `mode`, and `subject` only when entitled). Masked senders omit `underAgreementId` / `presentedAs`.
+- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may echo an `rpb_*` as `receiverId` — the backend resolves it in-room.
+
+Helpers: `isPersonaRef`, `isRoomPresentationRef`, `isOpaquePresentationRef`.
+
 #### Agent Search Client
 
 Search for agents:

package/dist/ConnectionManager.d.ts

@@ -1,87 +1,51 @@
-import { type InboxOperatorAgentEntry } from './http/InboxClient.js';
 type OpenFn = () => Promise<unknown>;
 type CloseFn = (handle: unknown) => Promise<void>;
-export interface StartAgentOptions {
-    /**
-     * Keep this host running until it is stopped explicitly — exempt from the
-     * idle sweep, last choice for LRU eviction. For agents the operator named
-     * (launcher `preStart` / `WAKE_AGENTS`): they were started because someone
-     * decided they must be up, not because work arrived, so "no work for a
-     * while" is not a reason to retire them.
-     */
-    pinned?: boolean;
-}
 export interface ConnectionManagerMeta {
     domain?: string;
     expertise?: string[];
     tags?: string[];
     [key: string]: unknown;
 }
-export interface ConnectionManagerOptions {
-    maxActive?: number;
-    idleTimeoutMs?: number;
-    /**
-     * Fleet control (delivery law, phase 4): the operator key whose owned agents
-     * this manager lazily starts. `start()` long-polls `GET /inbox/operator` with
-     * this key; when an agent's slice shows actionable content, it starts that
-     * agent's host (which then consumes via its own per-agent inbox loop). No
-     * socket, no push notification — lazy process management driven by the poll. `wsUrl`
-     * is accepted for back-compat but unused (the poll is HTTP).
-     */
-    control?: {
-        wsUrl?: string;
-        operatorKey?: string;
-    };
-    /**
-     * Gate on the operator-poll lazy start (ZIG-910). Called for each agent
-     * slice with actionable content before its host is started; return false to
-     * leave the host down this pass. The slice stays in later envelopes (reading
-     * never acks), so the gate is consulted again on every poll. Explicit
-     * `startAgent()` calls are not gated. Default: everything actionable starts.
-     */
-    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
-}
 export interface QueryFilter {
     domain?: string;
     expertise?: string[];
     tags?: string[];
 }
+/**
+ * ConnectionManager — the set of agent hosts this process runs.
+ *
+ * Every registered agent is connected and stays connected (ZIG-1108). There is
+ * no subset, no cap, no idle sweep and no lifecycle policy: an agent is alive
+ * because its launcher registered it, and the only thing that takes it down is
+ * the process exiting. Whether work has arrived recently is not a fact about
+ * whether an agent should exist.
+ *
+ * What this replaced: an operator long-poll that asked the backend which agents
+ * had mail, an LRU that evicted hosts past `maxActive`, an idle timer that slept
+ * quiet hosts, and a `pinned` flag to exempt the ones an operator had named.
+ * Together they made liveness depend on someone remembering to edit a Terraform
+ * string, and cost a fleet-wide sweep per poll to find out nothing had changed.
+ */
 export declare class ConnectionManager {
-    private maxActive;
-    private idleTimeoutMs;
-    private _operatorKey;
-    private _polling;
-    private _pollDone;
     private _entries;
     private _active;
     private _meta;
     private _starting;
-    private _pinned;
-    private _shouldLazyStart;
-    constructor({ maxActive, idleTimeoutMs, control, shouldLazyStart }?: ConnectionManagerOptions);
+    constructor();
     register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
-    start(operatorKey?: string): void;
-    stop(): Promise<void>;
     /**
-     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
-     * owned agent whose slice is actionable and not already running. The started
-     * host consumes + acks via its own per-agent inbox loop, so this loop never
-     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
-     * the loop never exits until `stop()` (nothing to resynchronize).
+     * Connect every registered agent. One host's failure to come up is reported
+     * and does not hold back the rest — its own transport retries, and a fleet
+     * where 28 of 29 are live is not a launch worth aborting.
      */
-    private _runOperatorPoll;
-    startAgent(id: string, { pinned }?: StartAgentOptions): Promise<unknown>;
+    connectAll(): Promise<void>;
+    startAgent(id: string): Promise<unknown>;
     sleep(id: string): Promise<void>;
     sleepAll(): Promise<void>;
-    touch(id: string): void;
     list(): string[];
     listActive(): string[];
-    listPinned(): string[];
     get size(): number;
     query({ domain, expertise, tags }?: QueryFilter): string[];
     getMeta(id: string): ConnectionManagerMeta | undefined;
-    private _scheduleIdle;
-    private _resetTimer;
-    private _evictLRU;
 }
 export {};

package/dist/ConnectionManager.js

@@ -1,36 +1,29 @@
-import { InboxClient } from './http/InboxClient.js';
 import { runtimeLog } from './shared/runtimeLog.js';
-import { isRateLimited } from './shared/rateLimit.js';
-const OPERATOR_POLL_WAIT_SECONDS = 25;
-const POLL_BACKOFF_BASE_MS = 1_000;
-const POLL_BACKOFF_MAX_MS = 30_000;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+/**
+ * ConnectionManager — the set of agent hosts this process runs.
+ *
+ * Every registered agent is connected and stays connected (ZIG-1108). There is
+ * no subset, no cap, no idle sweep and no lifecycle policy: an agent is alive
+ * because its launcher registered it, and the only thing that takes it down is
+ * the process exiting. Whether work has arrived recently is not a fact about
+ * whether an agent should exist.
+ *
+ * What this replaced: an operator long-poll that asked the backend which agents
+ * had mail, an LRU that evicted hosts past `maxActive`, an idle timer that slept
+ * quiet hosts, and a `pinned` flag to exempt the ones an operator had named.
+ * Together they made liveness depend on someone remembering to edit a Terraform
+ * string, and cost a fleet-wide sweep per poll to find out nothing had changed.
+ */
 export class ConnectionManager {
-    maxActive;
-    idleTimeoutMs;
-    _operatorKey;
-    _polling;
-    _pollDone;
     _entries;
     _active;
     _meta;
     _starting;
-    _pinned;
-    _shouldLazyStart;
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000, control, shouldLazyStart } = {}) {
-        this.maxActive = maxActive;
-        this.idleTimeoutMs = idleTimeoutMs;
-        this._shouldLazyStart = shouldLazyStart ?? null;
-        this._operatorKey = control?.operatorKey ?? null;
-        this._polling = false;
-        this._pollDone = null;
+    constructor() {
         this._entries = new Map();
         this._active = new Map();
         this._meta = new Map();
         this._starting = new Map();
-        this._pinned = new Set();
     }
     register(id, openFn, closeFn, meta) {
         if (!id)
@@ -43,103 +36,34 @@ export class ConnectionManager {
         if (meta)
             this._meta.set(id, meta);
     }
-    start(operatorKey) {
-        if (operatorKey)
-            this._operatorKey = operatorKey;
-        if (this._polling || !this._operatorKey)
-            return;
-        this._polling = true;
-        this._pollDone = this._runOperatorPoll(this._operatorKey);
-    }
-    async stop() {
-        this._polling = false;
-        if (this._pollDone)
-            await this._pollDone.catch(() => { });
-        this._pollDone = null;
-        await this.sleepAll();
-    }
     /**
-     * Fleet lazy-start loop: long-poll the operator inbox and start a host for any
-     * owned agent whose slice is actionable and not already running. The started
-     * host consumes + acks via its own per-agent inbox loop, so this loop never
-     * acks — it only decides which hosts to run. Errors retry with backoff+jitter;
-     * the loop never exits until `stop()` (nothing to resynchronize).
+     * Connect every registered agent. One host's failure to come up is reported
+     * and does not hold back the rest — its own transport retries, and a fleet
+     * where 28 of 29 are live is not a launch worth aborting.
      */
-    async _runOperatorPoll(operatorKey) {
-        // No agentId → operator-level multiplex read (transport auth only).
-        const inbox = new InboxClient(operatorKey);
-        let consecutiveErrors = 0;
-        while (this._polling) {
-            try {
-                // Roster scoping (ZIG-965): only agents this manager can actually
-                // start are worth sweeping server-side. Without it a partial launcher
-                // (ONLY_AGENTS) paid for a sweep of the owner's whole seeded fleet.
-                //
-                // Already-running agents are excluded: this loop's only job is
-                // lazy-start, and a running host polls its own inbox. Sending them
-                // made the server answer for agents whose entry we then discarded
-                // below — pure duplicate work, growing with how healthy the fleet is.
-                const startable = [...this._entries.keys()].filter((id) => !this._active.has(id));
-                const env = await inbox.getOperatorInbox({
-                    waitSeconds: OPERATOR_POLL_WAIT_SECONDS,
-                    agents: startable,
-                });
-                consecutiveErrors = 0;
-                for (const entry of env.agents) {
-                    const id = entry.agentId;
-                    // Only slices with actionable content are listed; start the host if
-                    // it isn't already running and we know how to open it.
-                    if (!id || this._active.has(id) || !this._entries.has(id))
-                        continue;
-                    if (this._shouldLazyStart && !this._shouldLazyStart(entry))
-                        continue;
-                    this.startAgent(id).catch((err) => runtimeLog.warn('ConnectionManager', `lazy-start("${id}") failed: ${err.message}`));
-                }
-            }
-            catch (err) {
-                if (!this._polling)
-                    break;
-                consecutiveErrors++;
-                // ZIG-1019: same rule as the per-agent loop — when the server throttles
-                // us it also says for how long, and retrying sooner just spends more of
-                // the budget we were told we are out of.
-                const throttleMs = isRateLimited(err) ? (err.retryAfterMs ?? 30_000) : null;
-                if (throttleMs !== null) {
-                    consecutiveErrors = 0;
-                    runtimeLog.warn('ConnectionManager', `operator poll throttled: ${err.message} — waiting ${Math.round(throttleMs)}ms as instructed`);
-                    await sleep(throttleMs);
-                    continue;
-                }
-                const backoff = Math.min(POLL_BACKOFF_MAX_MS, POLL_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
-                const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14);
-                runtimeLog.warn('ConnectionManager', `operator poll failed (#${consecutiveErrors}): ${err.message} — retrying in ~${Math.round(jitter)}ms`);
-                await sleep(jitter);
-            }
-        }
+    async connectAll() {
+        const ids = [...this._entries.keys()];
+        // The count is the cost: every registered agent is one WS connection plus
+        // one inbox long-poll, held for the life of the process. There is no cap,
+        // so a registration list that balloons shows up here first — loudly, with
+        // the number, before the sockets open.
+        runtimeLog.info('ConnectionManager', `connecting all ${ids.length} registered agent(s) — one connection + inbox long-poll each, for the life of the process`);
+        await Promise.all(ids.map((id) => this.startAgent(id).catch((err) => runtimeLog.warn('ConnectionManager', `start("${id}") failed: ${err.message}`))));
     }
-    async startAgent(id, { pinned = false } = {}) {
-        // Recorded before any await so a pin is never lost to a concurrent
-        // unpinned start of the same id.
-        if (pinned)
-            this._pinned.add(id);
+    async startAgent(id) {
         const existing = this._active.get(id);
-        if (existing) {
-            this._resetTimer(id);
-            return existing.handle;
-        }
+        if (existing)
+            return existing;
         const pending = this._starting.get(id);
         if (pending)
             return pending;
         const entry = this._entries.get(id);
         if (!entry)
             throw new Error(`[ConnectionManager] unknown id: "${id}"`);
-        if (this._active.size >= this.maxActive)
-            await this._evictLRU();
         const startPromise = (async () => {
             try {
                 const handle = await entry.openFn();
-                this._active.set(id, { handle, timer: null, lastActive: Date.now() });
-                this._scheduleIdle(id);
+                this._active.set(id, handle);
                 return handle;
             }
             finally {
@@ -150,22 +74,19 @@ export class ConnectionManager {
         return startPromise;
     }
     async sleep(id) {
-        const entry = this._active.get(id);
-        if (!entry)
+        if (!this._active.has(id))
             return;
-        clearTimeout(entry.timer);
+        const handle = this._active.get(id);
         this._active.delete(id);
         const reg = this._entries.get(id);
         if (reg)
-            await reg.closeFn(entry.handle);
+            await reg.closeFn(handle);
     }
     async sleepAll() {
         await Promise.all([...this._active.keys()].map(id => this.sleep(id)));
     }
-    touch(id) { this._resetTimer(id); }
     list() { return [...this._entries.keys()]; }
     listActive() { return [...this._active.keys()]; }
-    listPinned() { return [...this._pinned]; }
     get size() { return this._entries.size; }
     query({ domain, expertise, tags } = {}) {
         const results = [];
@@ -181,54 +102,4 @@ export class ConnectionManager {
         return results;
     }
     getMeta(id) { return this._meta.get(id); }
-    _scheduleIdle(id) {
-        const entry = this._active.get(id);
-        if (!entry)
-            return;
-        clearTimeout(entry.timer);
-        // A pinned host has no idle timer at all. Empty polls don't count as
-        // activity (only delivered items call touch()), so a pinned agent nobody
-        // talks to would otherwise be swept — and with lazy start unable to keep
-        // up at fleet size, nothing brings it back until the process restarts.
-        if (this._pinned.has(id)) {
-            entry.timer = null;
-            return;
-        }
-        entry.timer = setTimeout(() => {
-            this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
-        }, this.idleTimeoutMs);
-    }
-    _resetTimer(id) {
-        const entry = this._active.get(id);
-        if (!entry)
-            return;
-        entry.lastActive = Date.now();
-        this._scheduleIdle(id);
-    }
-    async _evictLRU() {
-        // Pinned hosts are the last to go: pick the LRU unpinned one, and only
-        // fall back to a pinned one when every active host is pinned. maxActive
-        // stays a hard cap — a pin outranks other agents, not the capacity limit —
-        // but say so, because it means more agents were pinned than can run.
-        const oldestOf = (ids) => {
-            let oldest = null;
-            for (const id of ids) {
-                const entry = this._active.get(id);
-                const oldestEntry = oldest ? this._active.get(oldest) : null;
-                if (!entry)
-                    continue;
-                if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
-                    oldest = id;
-            }
-            return oldest;
-        };
-        const active = [...this._active.keys()];
-        const victim = oldestOf(active.filter(id => !this._pinned.has(id))) ?? oldestOf(active);
-        if (!victim)
-            return;
-        if (this._pinned.has(victim)) {
-            runtimeLog.warn('ConnectionManager', `evicting pinned "${victim}": all ${active.length} active hosts are pinned and maxActive=${this.maxActive} is reached — pin fewer agents or raise maxActive`);
-        }
-        await this.sleep(victim);
-    }
 }

package/dist/capabilities/agreements.js

@@ -1,5 +1,5 @@
 import { claimOpenAgreement } from '../http/agreementFlows.js';
-import { linkIsReachOnly, linkSummary } from './links.js';
+import { linkIsReachOnly } from './links.js';
 import { fullCreds } from './types.js';
 /**
  * ZIG-1021 — the one claim verb. Quests, standing offers, and link invites
@@ -29,7 +29,7 @@ export const agreementClaimCapability = {
                 status: 'linked',
                 kind,
                 message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
-                agreement: linkSummary(agreement),
+                agreement,
             };
         }
         return {

package/dist/capabilities/artifacts.js

@@ -45,7 +45,7 @@ export const recordArtifactCapability = {
         chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Optional agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+            description: 'Optional agreement scope — for a hire deliverable, prefer this. Mutually exclusive with chatId: pass one, not both.',
         },
         taskId: {
             type: 'string',
@@ -63,12 +63,13 @@ export const recordArtifactCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const agreementId = args['agreementId'];
-        // Agreement wins when both scopes arrive. Models naturally pass the chat
-        // they are standing in alongside the agreement they deliver under; a hard
-        // xor here failed the deliverable at the last step of a finished task
-        // (ZIG-924 dogfood). The backend accepts at most one — we resolve the
-        // ambiguity at the exposed surface instead of erroring.
-        const chatId = agreementId ? undefined : args['chatId'];
+        // Both containers is refused, not resolved. This used to drop chatId and
+        // call agreement the winner — two answers to one call, and the silent one
+        // was worse: the artifact landed somewhere the caller had just been told it
+        // would also appear. The refusal itself lives in ArtifactsClient, the one
+        // gate every writer goes through, so this surface cannot drift from the
+        // others by wording its own verdict (ZIG-1075).
+        const chatId = args['chatId'];
         // ZIG-1037: no scope is legal. The throw that used to live here ("Pass
         // chatId or agreementId") is the exact failure this ticket removed — it cost
         // a live agent a turn mid-delivery for naming no container, when the record
@@ -80,7 +81,7 @@ export const recordArtifactCapability = {
         const contentType = args['content_type'];
         const taskId = args['taskId'];
         const creds = fullCreds(env);
-        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({
+        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
             text: args['text'],
             visibility,
             chatId,
@@ -128,7 +129,7 @@ export const listArtifactsCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
-        return new ArtifactsClient(creds.operatorKey, creds.agentId).list({ authoredBy: 'me' }, {
+        return new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
             after: args['after'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
@@ -248,7 +249,7 @@ export const attachArtifactCapability = {
             throw new Error('role must be input or output');
         }
         const creds = fullCreds(env);
-        const client = new ArtifactsClient(creds.operatorKey, creds.agentId);
+        const client = new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId);
         if (chatId) {
             await client.attachToChat(artifactId, chatId);
             return {

package/dist/capabilities/connections.js

@@ -97,7 +97,7 @@ export const requestConnectionCapability = {
                 note: env.surface === 'mcp'
                     ? 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
                         'Once approved, the connection + grant appear in ziggs_connection_list for ziggs_connection_proxy.'
-                    : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
+                    : 'A connection-consent card is now in the chat awaiting your principal — they approve it right there. ' +
                         'Once approved, the connection + grant appear in grant_list (scopeKind=connection) / connection_list_grants for connection_proxy.',
             };
         }

package/dist/capabilities/context.js

@@ -1,15 +1,9 @@
-import { ContextReadClient } from '../http/ContextReadClient.js';
+import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient } from '../http/ContextDiscoveryClient.js';
 import { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fetchMyOrgs, resolveOrgSelector } from '../http/OrgsClient.js';
 import { fullCreds } from './types.js';
-const CONTEXT_READ_TYPES = [
-    'messages',
-    'artifacts',
-    'agreements',
-    'tasks',
-];
 // ZIG-1037: `artifact` joined the context rail. Delegating an artifact grant
 // onward works (same kind, same id — an exact re-grant); narrowing a container
 // grant DOWN to an artifact inside it is deliberately not supported yet.
@@ -49,12 +43,26 @@ export async function resolveOrgScopeId(env, scopeId) {
     const lister = env.surface === 'mcp' ? 'ziggs_org_list' : 'your org list';
     throw new Error(`No org named "${scopeId}" in your memberships — use ${lister} to see them, or pass the org id.`);
 }
+/**
+ * Which `via` each read type accepts, rendered for the tool text. Generated from
+ * CONTEXT_READ_VIA so the pairing an agent is told about and the pairing the
+ * call actually accepts are one statement — the prose that used to enumerate
+ * these by hand had already drifted from the server's list.
+ */
+const VIA_BY_TYPE = CONTEXT_READ_TYPES.map((t) => `${t} via ${viaHint(t)}`).join('; ');
+/**
+ * The one fact about `artifact:<id>` that both surfaces must state: it is how you
+ * reach an artifact no container can return. Shared for the same reason the
+ * pairings above are generated — hand-copied prose is what drifted.
+ */
+const ARTIFACT_VIA_NOTE = 'via=artifact:<id> is a point read of one named artifact and the ONLY way to ' +
+    'read one attached to no chat, agreement or task';
 export const contextReadCapability = {
     key: 'context_read',
     names: { sdk: 'context_read', mcp: 'ziggs_context_read' },
     descriptions: {
-        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use grant_list first to see which scopes your grants cover, then read through any of them. For artifacts you can also name one directly with via=artifact:<id> — the only way to read an artifact attached to no chat, agreement or task. Cursored; all access is grant-fenced server-side.',
-        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id> — plus via=artifact:<id> for artifacts, a point read of one named artifact and the ONLY way to read one that is attached to no container (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.',
+        sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
+        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
     },
     annotation: 'read-only',
     params: {
@@ -67,7 +75,7 @@ export const contextReadCapability = {
         via: {
             type: 'string',
             required: true,
-            description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>. For type=artifacts also artifact:<id> to read that one artifact.',
+            description: `Scope entry you hold, as <kind>:<id>. Accepted per type — ${VIA_BY_TYPE}.`,
         },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         after: { type: 'string', description: 'ISO timestamp for forward-delta (messages/artifacts)' },
@@ -93,11 +101,21 @@ export const contextReadCapability = {
         const via = args['via'];
         if (!via)
             throw new Error('via is required');
+        // Same verdict the server gives, given at the call site so the reason
+        // arrives with the mistake. Never a softer one: a client that "fixes" an
+        // argument the server would reject is a second answer to one call.
+        const parsed = parseVia(via);
+        if (!parsed) {
+            throw new Error(`via must be <kind>:<id> — one of ${viaHint(type)} for type=${type}`);
+        }
+        if (!CONTEXT_READ_VIA[type].includes(parsed.kind)) {
+            throw new Error(`${type} reads accept via=${viaHint(type)} — not ${parsed.kind}:<id>`);
+        }
         const direction = args['direction'];
         if (direction !== undefined && direction !== 'forward') {
             throw new Error('direction must be "forward"');
         }
-        return new ContextReadClient(creds.operatorKey, creds.agentId).read(type, {
+        return new ContextReadClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).read(type, {
             via,
             cursor: args['cursor'],
             after: args['after'],

package/dist/capabilities/grants.d.ts

@@ -4,6 +4,13 @@ import { type CapabilityDefinition } from './types.js';
  * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
+ *
+ * ZIG-1088 — HOLD, not reach. `GET /grants` queries three row collections and
+ * nothing else; the implicit arms in AccessService (authorship, chat
+ * membership, agreement party, org membership) leave no row behind, so a reader
+ * can be entitled to something this list will never mention. The description
+ * says so, because the old "the single answer" wording was read as completeness
+ * and an empty list as "no access".
  */
 export declare const listGrantsCapability: CapabilityDefinition;
 export declare const GRANTS_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/grants.js

@@ -26,13 +26,20 @@ function parseScopeKinds(raw) {
  * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
+ *
+ * ZIG-1088 — HOLD, not reach. `GET /grants` queries three row collections and
+ * nothing else; the implicit arms in AccessService (authorship, chat
+ * membership, agreement party, org membership) leave no row behind, so a reader
+ * can be entitled to something this list will never mention. The description
+ * says so, because the old "the single answer" wording was read as completeness
+ * and an empty list as "no access".
  */
 export const listGrantsCapability = {
     key: 'grant_list',
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     descriptions: {
-        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
-        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_context_read to pin a specific grant, or ziggs_context_expand_reach to enumerate a scope.',
+        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. To answer "what can I reach?" instead, use context_expand_reach to enumerate a scope, or context_read to read through a grant.',
+        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. To answer "what can I reach?" instead, use ziggs_context_expand_reach to enumerate a scope, or pass a grantId to ziggs_context_read to pin a specific grant.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -1,6 +1,6 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/index.js

@@ -1,6 +1,6 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from './payments.js';
-export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkSummary, linkIsReachOnly, } from './links.js';
+export { LINK_CAPABILITIES, createLinkInviteCapability, listLinksCapability, linkIsReachOnly, } from './links.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability } from './agreements.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';

package/dist/capabilities/links.d.ts

@@ -1,12 +1,4 @@
-import type { Agreement } from '../types.js';
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
-/**
- * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
- * block, approvals array, and Mongo internals are noise on a trust
- * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
- * return it too (they used to leak the raw agreement doc).
- */
-export declare function linkSummary(a: Agreement): Record<string, unknown>;
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
  *