@ziggs-ai/api-client 0.7.1 → 0.9.0

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/capabilities/artifacts.d.ts

@@ -1,3 +1,31 @@
 import { type CapabilityDefinition } from './types.js';
 export declare const recordArtifactCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — the artifacts you wrote, across every scope and none.
+ *
+ * The scope listings (`context_read` via chat / agreement / task) read attach
+ * tables, so a free-standing artifact appears in none of them. This is how an
+ * agent finds what it recorded without naming a container.
+ */
+export declare const listArtifactsCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — hand one artifact you authored to one other agent.
+ *
+ * Deliberately not part of `context_delegate`: there is no parent grant to
+ * attenuate here. An agent holds no grant over its own output — authorship is
+ * the authority, and it belongs to the agent's owner, which is why a receiver
+ * outside that owner's trust boundary needs their approval. What counts as
+ * "inside" is the shared new-party policy, not a local rule: same owner, same
+ * org, or an active agent link.
+ */
+export declare const shareArtifactCapability: CapabilityDefinition;
+/**
+ * ZIG-1037 — attach an artifact you already have to a chat or a task.
+ *
+ * The other half of "record now, decide where later". Attaching confers nothing
+ * by itself: it puts the artifact inside the container, and that container's
+ * audience can read it from then on. Use this to publish to a room or bind a
+ * deliverable to a task; use artifact_share to hand it to ONE agent instead.
+ */
+export declare const attachArtifactCapability: CapabilityDefinition;
 export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -1,4 +1,5 @@
 import { ArtifactsClient } from '../http/ArtifactsClient.js';
+import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { fullCreds } from './types.js';
 /**
  * ZIG-560 teaching: name the result slot on the success path so an agent finds
@@ -20,8 +21,14 @@ export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
     descriptions: {
-        sdk: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. For a finished deliverable, set content_type=result and pass taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
-        mcp: 'Write an artifact to a chat or agreement scope. Set visibility explicitly. ' +
+        sdk: 'Write an artifact. Scope is optional: pass agreementId or chatId to record it there, ' +
+            'or pass no scope at all to record it as yours alone and attach it somewhere later. ' +
+            'Set visibility explicitly. For a finished deliverable, set content_type=result and pass ' +
+            'taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+        mcp: 'Write an artifact. Scope is optional — pass agreementId or chatId to record it into that ' +
+            'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
+            'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
+            'recording with none always succeeds. Set visibility explicitly. ' +
             'For a finished deliverable, set content_type=result and pass taskId to bind it to the task. ' +
             'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only).',
     },
@@ -32,16 +39,17 @@ export const recordArtifactCapability = {
             type: 'string',
             required: true,
             enum: ['chat', 'agent-private'],
-            description: 'chat = visible to scope parties; agent-private = your eyes only',
+            description: 'chat = the scope’s parties can read it; agent-private = not shared with them. ' +
+                'Neither is permanent: you can share any artifact later with a specific agent.',
         },
-        chatId: { type: 'string', description: 'Target chat scope' },
+        chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Target 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',
-            description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
+            description: 'Optional task binding. Valid on its own — a task-bound deliverable needs no chat or agreement.',
         },
         content_type: {
             type: 'string',
@@ -55,15 +63,17 @@ 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 still enforces exactly-one — we resolve
-        // the ambiguity at the exposed surface instead of erroring.
-        const chatId = agreementId ? undefined : args['chatId'];
-        if (!chatId && !agreementId) {
-            throw new Error('Pass chatId or agreementId');
-        }
+        // 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
+        // itself never needed one.
         const visibility = args['visibility'];
         if (visibility !== 'chat' && visibility !== 'agent-private') {
             throw new Error('visibility must be chat or agent-private');
@@ -71,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,
@@ -91,4 +101,177 @@ export const recordArtifactCapability = {
         };
     },
 };
-export const ARTIFACT_CAPABILITIES = [recordArtifactCapability];
+/**
+ * ZIG-1037 — the artifacts you wrote, across every scope and none.
+ *
+ * The scope listings (`context_read` via chat / agreement / task) read attach
+ * tables, so a free-standing artifact appears in none of them. This is how an
+ * agent finds what it recorded without naming a container.
+ */
+export const listArtifactsCapability = {
+    key: 'artifact_list',
+    names: { sdk: 'artifact_list', mcp: 'ziggs_artifact_list' },
+    descriptions: {
+        sdk: 'List artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Forward-delta with `after`.',
+        mcp: 'List artifacts YOU authored, across every scope and none. Use this to find something you ' +
+            'recorded free-standing (no chat/agreement/task), which the scope reads cannot return. ' +
+            'To read an artifact someone shared WITH you, use ziggs_context_read with via=artifact:<id>; ' +
+            'to see what has been shared with you, use ziggs_grant_list with scopeKind=artifact.',
+    },
+    annotation: 'read-only',
+    params: {
+        after: {
+            type: 'string',
+            description: 'ISO timestamp — return only artifacts written strictly after this',
+        },
+        limit: { type: 'number', description: 'Page size (server default when omitted)' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        return new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
+            after: args['after'],
+            limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+        });
+    },
+};
+/**
+ * ZIG-1037 — hand one artifact you authored to one other agent.
+ *
+ * Deliberately not part of `context_delegate`: there is no parent grant to
+ * attenuate here. An agent holds no grant over its own output — authorship is
+ * the authority, and it belongs to the agent's owner, which is why a receiver
+ * outside that owner's trust boundary needs their approval. What counts as
+ * "inside" is the shared new-party policy, not a local rule: same owner, same
+ * org, or an active agent link.
+ */
+export const shareArtifactCapability = {
+    key: 'artifact_share',
+    names: { sdk: 'artifact_share', mcp: 'ziggs_artifact_share' },
+    descriptions: {
+        sdk: 'Share an artifact you authored with another agent — just that artifact, no chat or agreement. An agent already connected to you (same owner, same org, or an active link) gets it immediately; anyone else is offered to your owner to approve.',
+        mcp: 'Share ONE artifact you authored with another agent, without sharing any chat or agreement ' +
+            'it sits in. Only the authoring agent can call this. A receiver already connected to you — ' +
+            'same owner, same org, or an active link — is granted immediately. Any other agent is ' +
+            'offered to your owner to approve, and the reply is { status: "pending_approval", ' +
+            'agreementId } — nothing is shared until they do. Pass chatId to have that approval appear ' +
+            'in the chat you are working in. The receiver then reads it with ziggs_context_read ' +
+            'via=artifact:<id>.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: {
+            type: 'string',
+            required: true,
+            description: 'The artifact to share — you must be its author',
+        },
+        holderId: { type: 'string', required: true, description: 'Agent id that receives it' },
+        expiresAt: {
+            type: 'string',
+            description: 'ISO-8601 expiry; omit for the default grant lifetime',
+        },
+        chatId: {
+            type: 'string',
+            description: 'Chat to surface the approval request in, when the receiver’s owner has to approve',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const holderId = args['holderId'];
+        if (!holderId)
+            throw new Error('holderId is required');
+        const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).shareArtifact(artifactId, {
+            holderId,
+            expiresAt: args['expiresAt'],
+            chatId: args['chatId'],
+        });
+        if (result.status === 'pending_approval') {
+            return {
+                ok: true,
+                ...result,
+                note: `Not shared yet — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}.`,
+            };
+        }
+        return {
+            ok: true,
+            ...result,
+            note: `${holderId} can now read artifact ${artifactId} with via=artifact:${artifactId}.`,
+        };
+    },
+};
+/**
+ * ZIG-1037 — attach an artifact you already have to a chat or a task.
+ *
+ * The other half of "record now, decide where later". Attaching confers nothing
+ * by itself: it puts the artifact inside the container, and that container's
+ * audience can read it from then on. Use this to publish to a room or bind a
+ * deliverable to a task; use artifact_share to hand it to ONE agent instead.
+ */
+export const attachArtifactCapability = {
+    key: 'artifact_attach',
+    names: { sdk: 'artifact_attach', mcp: 'ziggs_artifact_attach' },
+    descriptions: {
+        sdk: 'Attach an artifact you can read to a chat or a task. Everyone in that chat / party to that task can read it from then on. Use artifact_share to give it to one specific agent instead.',
+        mcp: 'Attach an existing artifact to a chat or a task — the way a free-standing artifact (one you ' +
+            'recorded with no scope) reaches an audience. Pass exactly one of chatId or taskId. Everyone ' +
+            'in that chat, or party to that task, can read it from then on; attaching gives you nothing ' +
+            'new yourself. You must already be able to read the artifact AND belong to the container. ' +
+            'To hand it to ONE specific agent without opening a chat, use ziggs_artifact_share instead.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'Artifact to attach' },
+        chatId: { type: 'string', description: 'Chat to attach it to' },
+        taskId: { type: 'string', description: 'Task to attach it to' },
+        role: {
+            type: 'string',
+            enum: ['input', 'output'],
+            description: 'Task attach only: output (a deliverable, default) or input (something the task consumes). ' +
+                'A link’s role is set once — re-attaching with a different role is refused, not changed.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const chatId = args['chatId'];
+        const taskId = args['taskId'];
+        if (!!chatId === !!taskId) {
+            throw new Error('Pass exactly one of chatId or taskId');
+        }
+        const role = args['role'] ?? 'output';
+        if (role !== 'input' && role !== 'output') {
+            throw new Error('role must be input or output');
+        }
+        const creds = fullCreds(env);
+        const client = new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId);
+        if (chatId) {
+            await client.attachToChat(artifactId, chatId);
+            return {
+                ok: true,
+                artifactId,
+                chatId,
+                note: `Everyone in chat ${chatId} can now read artifact ${artifactId}.`,
+            };
+        }
+        await client.attachToTask(artifactId, taskId, role);
+        return {
+            ok: true,
+            artifactId,
+            taskId,
+            role,
+            note: `Artifact ${artifactId} is attached to task ${taskId} as ${role}; the task's parties can read it.`,
+        };
+    },
+};
+export const ARTIFACT_CAPABILITIES = [
+    recordArtifactCapability,
+    listArtifactsCapability,
+    shareArtifactCapability,
+    attachArtifactCapability,
+];

package/dist/capabilities/context.js

@@ -1,16 +1,13 @@
-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 } from '../http/grants.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',
-];
-const GRANT_SCOPE_KINDS = ['chat', 'agreement', 'org'];
+// 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.
+const GRANT_SCOPE_KINDS = CONTEXT_GRANT_SCOPE_KINDS;
 const CONTEXT_TEMPORALS = ['from-now', 'from-start'];
 /**
  * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
@@ -46,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. 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>. 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: {
@@ -64,7 +75,7 @@ export const contextReadCapability = {
         via: {
             type: 'string',
             required: true,
-            description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>',
+            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)' },
@@ -90,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'],
@@ -109,8 +130,8 @@ export const contextExpandReachCapability = {
     key: 'context_expand_reach',
     names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
     descriptions: {
-        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
-        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
+        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — the grant IS one artifact, so read it directly with context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — that grant IS a single artifact, so do not read the empty map as a dead grant: read the artifact with ziggs_context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {
@@ -179,7 +200,7 @@ export const contextDelegateCapability = {
         }
         const scopeKind = args['scopeKind'];
         if (!GRANT_SCOPE_KINDS.includes(scopeKind)) {
-            throw new Error('scopeKind must be chat, agreement, or org');
+            throw new Error(`scopeKind must be one of ${GRANT_SCOPE_KINDS.join(', ')}`);
         }
         // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
         let scopeId = args['scopeId'];

package/dist/capabilities/grants.d.ts

@@ -1,9 +1,16 @@
 import { type CapabilityDefinition } from './types.js';
 /**
  * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org, connection, wallet), holder-scoped,
+ * (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

@@ -1,12 +1,11 @@
 import { GrantsClient } from '../http/GrantsClient.js';
+import { GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fullCreds } from './types.js';
-const SCOPE_KINDS = [
-    'chat',
-    'agreement',
-    'org',
-    'connection',
-    'wallet',
-];
+// BOTH the tool's param enum and its validator, so a missing kind makes the
+// filter the description advertises fail validation. Derived from the canonical
+// list next to the type rather than restated, because that is exactly how
+// `artifact` came to be advertised but not accepted.
+const SCOPE_KINDS = GRANT_SCOPE_KINDS;
 const HEALTHS = ['active', 'expired', 'revoked'];
 function parseScopeKinds(raw) {
     if (raw == null)
@@ -24,23 +23,30 @@ function parseScopeKinds(raw) {
 }
 /**
  * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org, connection, wallet), holder-scoped,
+ * (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), 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), 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: {
         scopeKind: {
             type: 'array',
             items: { type: 'string', enum: SCOPE_KINDS },
-            description: 'Rail filter (repeatable): chat | agreement | org (context) | connection | wallet. Omit for every rail you can read.',
+            description: 'Rail filter (repeatable): chat | agreement | org | artifact (context) | connection | wallet. Omit for every rail you can read.',
         },
         health: {
             type: 'string',

package/dist/capabilities/index.d.ts

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/types.d.ts

@@ -43,6 +43,7 @@ export interface CapabilityEnv {
     creds: {
         operatorKey: string;
         agentId?: string;
+        laneId?: string;
     };
     /** SDK runner base-URL override (BACKEND_URL / ZIGGS_BACKEND_URL). */
     baseUrl?: string;

package/dist/capabilities/types.js

@@ -1,11 +1,13 @@
 /** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
 export function fullCreds(env) {
-    const { operatorKey, agentId } = env.creds;
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
     if (!agentId)
         throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
+    // ZIG-1092 — the lane rides along so every Creds-based client sends
+    // X-Ziggs-Lane without each capability having to remember to.
+    return { operatorKey, agentId, ...(laneId ? { laneId } : {}) };
 }
 /**
  * Re-throw a client error with a capability-level prefix, preserving the HTTP