@ziggs-ai/api-client 0.14.3 → 0.16.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -9,6 +9,15 @@ export declare const agreementRequestCapability: CapabilityDefinition;
  * to be doing today, and the publish path says so at its own end
  * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
  * listing when the job ended.
+ *
+ * No price default here on purpose: an unstated price is a free hire, and the
+ * publish path is the one place that says so. Stating a price publishes a paid
+ * listing.
+ *
+ * No replay key either, and that one has a cost worth knowing: each call
+ * publishes a fresh row rather than replaying, and the previous listing is
+ * retired as it goes, so an agent that republishes leaves dead rows behind it.
+ * One listing per agent still holds; the churn does not.
  */
 export declare const agreementOfferCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -92,7 +92,7 @@ function engagementKindFrom(args) {
  */
 const MANDATE_PARAM = {
     type: 'string',
-    description: 'The active agreement whose work this is part of — the job you are doing. It becomes this engagement\'s parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job.',
+    description: "The active agreement whose work this is part of — the job you are doing. It becomes this engagement's parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job. It never names who you act for — the server reads that off the room or contract that woke you.",
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
@@ -122,10 +122,27 @@ const COUNTERPARTY_PARAM = {
     required: true,
     description: 'Agent or user id of the counterparty.',
 };
+/**
+ * Optional, because the server has always accepted a proposal without one and
+ * the client was the only thing refusing.
+ *
+ * The room is where a conversation about the terms happens; it is not how the
+ * counterparty is TOLD. A directed proposal is delivered to the party slots
+ * (the create-time agreement event targets parties, not a chat), so a chatless
+ * proposal lands in their inbox exactly like any other. What is lost is
+ * narrower than it sounds: the notice posted INTO a room, which is worth
+ * nothing when there is no room.
+ *
+ * Requiring it here meant a bookkeeping agreement between parties who have no
+ * conversation had to invent a chat id to exist. The lab's own self-hire did:
+ * it passed `lab-hire-<run>`, a chat that does not exist, which the server
+ * tolerates by falling back to the credential's tenant. A fiction the caller
+ * was forced to write down is worse than an absent field.
+ */
 const CHAT_PARAM = {
     type: 'string',
-    required: true,
-    description: 'The room this is proposed in — the counterparty reads it there.',
+    required: false,
+    description: 'The room this is proposed in, when there is one — the counterparty can read and discuss the terms there. Omit it for an agreement between parties with no conversation; the proposal still reaches them, it just has no room to be discussed in.',
 };
 /** Marketplace follow-up: a published listing is claimed, never countered. */
 function publishedNext(env) {
@@ -269,6 +286,15 @@ export const agreementRequestCapability = {
  * to be doing today, and the publish path says so at its own end
  * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
  * listing when the job ended.
+ *
+ * No price default here on purpose: an unstated price is a free hire, and the
+ * publish path is the one place that says so. Stating a price publishes a paid
+ * listing.
+ *
+ * No replay key either, and that one has a cost worth knowing: each call
+ * publishes a fresh row rather than replaying, and the previous listing is
+ * retired as it goes, so an agent that republishes leaves dead rows behind it.
+ * One listing per agent still holds; the churn does not.
  */
 export const agreementOfferCapability = {
     key: 'agreement_offer',

package/dist/capabilities/agreements.js

@@ -1,3 +1,4 @@
+import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
 import { fullCreds } from './types.js';
@@ -25,7 +26,7 @@ export function presentClaimResult(agreement, kind, env) {
     }
     if (agreement?.status !== 'active') {
         const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
-        const approveUrl = `${webAppOrigin(env)}/app/work/agreements/${agreement.agreementId}`;
+        const approveUrl = agreementAppUrl(webAppOrigin(env), agreement.agreementId);
         const remedy = held?.heldReason === 'contact-basis'
             ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
             : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';

package/dist/capabilities/artifacts.js

@@ -1,6 +1,7 @@
 import { ArtifactsClient } from '../http/ArtifactsClient.js';
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 /**
  * teaching: name the result slot on the success path so an agent finds
  * the right move unaided — worded in each surface's task grammar (SDK
@@ -90,6 +91,7 @@ async function recordFileArtifact(args, env, visibility) {
     const byteSize = bytes.byteLength;
     const uploaded = await client.uploadUrl({
         filename,
+        name: args['name']?.trim() || undefined,
         mime,
         // The byte length of what will be PUT, not of the base64 envelope — the
         // presign signs this number and S3 rejects a mismatch.
@@ -134,9 +136,8 @@ export const recordArtifactCapability = {
             'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
             ARTIFACT_RECORD_INLINE_CAP,
         mcp: 
-        // Canonical for ziggs-mcp (tools.ts must not override). Last paragraph is
-        // PROTOCOL.reporting copied verbatim — api-client cannot import ziggs-mcp;
-        // record-artifact-teaching.test.ts gates the live tool against both.
+        // Canonical for ziggs-mcp (tools.ts must not override). Shared protocol
+        // (where finished work goes) lives on connect instructions.
         'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
             'and completion all happen inside this one call, so there is no separate upload dance). ' +
             'Scope is optional — pass agreementId or chatId to record it into that ' +
@@ -144,8 +145,7 @@ export const recordArtifactCapability = {
             '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 contentType=result and pass taskId to bind it to the task. ' +
-            ARTIFACT_RECORD_INLINE_CAP +
-            ' Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.',
+            ARTIFACT_RECORD_INLINE_CAP,
     },
     annotation: 'write',
     params: {
@@ -157,6 +157,10 @@ export const recordArtifactCapability = {
             type: 'string',
             description: 'Base64 file bytes for a file artifact — requires filename and mime. This call presigns, uploads and completes; you never compute a checksum. Bytes over ~1MB will not fit in a tool call: use artifact_upload_url for those.',
         },
+        name: {
+            type: 'string',
+            description: 'Short name shown in lists (room, agreement, artifacts page). Pass this for a text deliverable so the other party can tell what it is without opening it. A file defaults to filename when omitted.',
+        },
         filename: {
             type: 'string',
             description: 'Original filename — required with contentBase64',
@@ -232,6 +236,7 @@ export const recordArtifactCapability = {
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
             text,
+            name: args['name']?.trim() || undefined,
             visibility,
             chatId,
             agreementId,
@@ -275,14 +280,19 @@ export const listArtifactsCapability = {
             description: 'ISO timestamp — return only artifacts written strictly after this',
         },
         limit: { type: 'number', description: 'Page size (server default when omitted)' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
-        return new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
+        const listed = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
             after: args['after'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
+        const fields = parseListFields(args['fields']);
+        return fields
+            ? { ...listed, artifacts: pickListedRows(listed.artifacts, fields) }
+            : listed;
     },
 };
 /**

package/dist/capabilities/connections.d.ts

@@ -1,4 +1,4 @@
-import { type CapabilityDefinition } from './types.js';
+import { type CapabilityDefinition } from "./types.js";
 export declare const connectionProxyCapability: CapabilityDefinition;
 export declare const requestConnectionCapability: CapabilityDefinition;
 export declare const CONNECTION_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/connections.js

@@ -1,115 +1,138 @@
-import { ConnectionsClient } from '../http/ConnectionsClient.js';
-import { rethrowWithContext, } from './types.js';
+import { ConnectionsClient } from "../http/ConnectionsClient.js";
+import { rethrowWithContext, } from "./types.js";
 function client(env) {
-    const { operatorKey, agentId } = env.creds;
+    // laneId, not just the key and the agent. The lane is which hire this wake is
+    // in, and the broker reads off it who the agent is acting for — which is what
+    // tells one hirer's grant from another's: an agent that serves several hirers
+    // is the holder of every grant it has been given, so the holder check alone
+    // cannot separate them. Every other Creds-based client already carries it.
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    return new ConnectionsClient(operatorKey, agentId, env.baseUrl);
+        throw new Error("operatorKey missing from tool context");
+    return new ConnectionsClient(operatorKey, agentId, env.baseUrl, laneId);
 }
 export const connectionProxyCapability = {
-    key: 'connection_proxy',
-    names: { sdk: 'connection_proxy', mcp: 'ziggs_connection_proxy' },
-    title: 'Use a stored connection',
+    key: "connection_proxy",
+    names: { sdk: "connection_proxy", mcp: "ziggs_connection_proxy" },
+    title: "Use a stored connection",
     descriptions: {
         sdk: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira) without ever seeing the credential. " +
-            'Calls the backend connections proxy with a grant the owner issued to this agent. ' +
+            "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use mcp_tool_call / mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Use grant_list (scopeKind=connection) or connection_list_grants first.",
         mcp: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list) without ever seeing the credential. " +
-            'Calls the backend connections proxy with a grant the owner issued to this agent. ' +
+            "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use ziggs_mcp_tool_call / ziggs_mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Call ziggs_connection_list first.",
     },
-    annotation: 'write',
+    annotation: "write",
     params: {
-        connectionId: { type: 'string', required: true, description: 'Connection to act on' },
+        connectionId: {
+            type: "string",
+            required: true,
+            description: "Connection to act on",
+        },
         grantId: {
-            type: 'string',
+            type: "string",
+            required: true,
+            description: "Grant the owner issued to this agent for the connection",
+        },
+        action: {
+            type: "string",
             required: true,
-            description: 'Grant the owner issued to this agent for the connection',
+            description: "Provider action, e.g. repo:read",
+        },
+        payload: {
+            type: "object",
+            description: "Action-specific arguments (provider-defined)",
         },
-        action: { type: 'string', required: true, description: 'Provider action, e.g. repo:read' },
-        payload: { type: 'object', description: 'Action-specific arguments (provider-defined)' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args['connectionId'])
-            throw new Error('connectionId is required');
-        if (!args['grantId'])
-            throw new Error('grantId is required');
-        if (!args['action'])
-            throw new Error('action is required');
+        if (!args["connectionId"])
+            throw new Error("connectionId is required");
+        if (!args["grantId"])
+            throw new Error("grantId is required");
+        if (!args["action"])
+            throw new Error("action is required");
         try {
             const result = await client(env).proxy({
-                connectionId: args['connectionId'],
-                grantId: args['grantId'],
-                action: args['action'],
-                payload: args['payload'],
+                connectionId: args["connectionId"],
+                grantId: args["grantId"],
+                action: args["action"],
+                payload: args["payload"],
             });
-            return { ok: true, action: args['action'], result };
+            return { ok: true, action: args["action"], result };
         }
         catch (e) {
-            rethrowWithContext(e, 'Connection proxy failed');
+            rethrowWithContext(e, "Connection proxy failed");
         }
     },
 };
 export const requestConnectionCapability = {
-    key: 'connection_request',
-    names: { sdk: 'connection_request', mcp: 'ziggs_connection_request' },
-    title: 'Ask your principal for a connection',
+    key: "connection_request",
+    names: { sdk: "connection_request", mcp: "ziggs_connection_request" },
+    title: "Ask your principal for a connection",
     descriptions: {
-        sdk: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
-            'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. ' +
-            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).',
-        mcp: 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
-            'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
-            'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.',
+        sdk: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
+            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. " +
+            "On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).",
+        mcp: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
+            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). " +
+            "On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.",
     },
-    annotation: 'write',
+    annotation: "write",
     params: {
         chatId: {
-            type: 'string',
+            type: "string",
+            required: true,
+            description: "The chat you are working in — the consent card is opened there",
+        },
+        serverUrl: {
+            type: "string",
             required: true,
-            description: 'The chat you are working in — the consent card is opened there',
+            description: "Remote MCP server URL (https)",
         },
-        serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
         tools: {
-            type: 'array',
-            items: { type: 'string' },
+            type: "array",
+            items: { type: "string" },
             required: true,
             description: "Tool names you want — become the grant's allowed_actions caveats",
         },
-        reason: { type: 'string', description: 'Plain-language reason shown to the human deciding' },
+        reason: {
+            type: "string",
+            description: "Plain-language reason shown to the human deciding",
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
-        if (!args['chatId'])
-            throw new Error('chatId is required');
-        if (!args['serverUrl'])
-            throw new Error('serverUrl is required');
-        const tools = args['tools'];
+        if (!args["chatId"])
+            throw new Error("chatId is required");
+        if (!args["serverUrl"])
+            throw new Error("serverUrl is required");
+        const tools = args["tools"];
         if (!Array.isArray(tools) || tools.length === 0) {
-            throw new Error('tools must be a non-empty array of tool names');
+            throw new Error("tools must be a non-empty array of tool names");
         }
         try {
             const result = await client(env).requestMcpConnection({
-                chatId: args['chatId'],
-                serverUrl: args['serverUrl'],
+                chatId: args["chatId"],
+                serverUrl: args["serverUrl"],
                 tools: tools,
-                reason: args['reason'],
+                reason: args["reason"],
             });
             return {
                 ok: true,
                 ...result,
-                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_mcp_tools_list / ziggs_mcp_tool_call.'
-                    : '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 mcp_tools_list / mcp_tool_call.',
+                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_mcp_tools_list / ziggs_mcp_tool_call."
+                    : "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 mcp_tools_list / mcp_tool_call.",
             };
         }
         catch (e) {
-            rethrowWithContext(e, 'Connection request failed');
+            rethrowWithContext(e, "Connection request failed");
         }
     },
 };

package/dist/capabilities/grants.js

@@ -1,6 +1,7 @@
 import { GrantsClient } from '../http/GrantsClient.js';
 import { GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 // 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
@@ -67,6 +68,7 @@ export const listGrantsCapability = {
         },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         limit: { type: 'number', description: 'Page size (server default when omitted)' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -80,7 +82,10 @@ export const listGrantsCapability = {
         if (roleArg !== undefined && roleArg !== 'holder' && roleArg !== 'issuer') {
             throw new Error('role must be holder or issuer');
         }
-        const { items, nextCursor, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).listGrants({
+        const { items, nextCursor, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl, 
+        // The lane, so the server answers with the grants THIS wake may spend
+        // rather than everything the agent holds across every customer.
+        creds.laneId).listGrants({
             scopeKind,
             scopeId: typeof args['scopeId'] === 'string' ? args['scopeId'] : undefined,
             role: roleArg,
@@ -89,9 +94,10 @@ export const listGrantsCapability = {
             cursor: args['cursor'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
+        const fields = parseListFields(args['fields']);
         return {
             count: items.length,
-            grants: items,
+            grants: pickListedRows(items, fields),
             nextCursor,
             ...(unreadableRails?.length ? { unreadableRails } : {}),
         };

package/dist/capabilities/index.d.ts

@@ -5,6 +5,7 @@ export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
 export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/index.js

@@ -5,6 +5,7 @@ export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
 export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/links.js

@@ -1,9 +1,9 @@
+import { resolveWebAppOrigin, connectInviteAppUrl } from '../utils/appUrls.js';
 import { createLink, listAgreements } from '../http/AgreementClient.js';
 import { nextCall } from './nextCall.js';
 import { fullCreds } from './types.js';
-const DEFAULT_WEB_URL = 'https://ziggsai.com';
 export function webAppOrigin(env) {
-    return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
+    return resolveWebAppOrigin(env.webUrl);
 }
 /**
  * The one thing an invite travels as: `/connect/<inviteId>`.
@@ -17,7 +17,7 @@ export function webAppOrigin(env) {
  * across two repos.
  */
 function inviteShareUrl(env, agreementId) {
-    return `${webAppOrigin(env)}/connect/${agreementId}`;
+    return connectInviteAppUrl(webAppOrigin(env), agreementId);
 }
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.
@@ -159,7 +159,7 @@ export const proposeLinkCapability = {
     handler: async (args, env) => {
         const to = args['to']?.trim();
         const maxClaims = args['maxClaims'];
-        const { shareUrl } = await createLink({
+        const { shareUrl, agreementId } = await createLink({
             ...(to ? { to } : {}),
             ...(args['message'] ? { description: args['message'] } : {}),
             ...(maxClaims == null || to ? {} : { maxClaims }),
@@ -168,9 +168,17 @@ export const proposeLinkCapability = {
         // back. That is the whole discipline: the caller knows whether it named
         // somebody, so branching on it discloses nothing, while branching on
         // anything the server learned about the target would.
+        //
+        // `agreementId` follows the same discipline: the route carries it for an
+        // agent id and an open invite and never for an email, so which of the two it
+        // is depends on what the caller passed and on nothing the server learned. It
+        // is what lets a caller reference the row and check on it; without it,
+        // several agents connecting in one run each minted a link toward the others
+        // in both directions, because none of them could ask.
         return {
             status: 'sent',
             shareUrl,
+            agreementId,
             message: to
                 ? `Invitation sent to ${to}. You will not be told whether they already had an account, whether you were already connected, or whether this repeated an earlier invitation — the answer is the same in every case, on purpose. It becomes a live connection when they accept. ${linkIsReachOnly(env)}`
                 : `Share link created, valid 7 days. Give your human shareUrl and nothing else: it is the whole invite. ${linkIsReachOnly(env)}`,

package/dist/capabilities/listedFields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opt-in row projection for list tools.
+ *
+ * List endpoints return the full row by default. Pass `fields` to keep only
+ * those keys — the same shape as Linear's `list_issues`. Envelope keys
+ * (count, nextCursor, hasMore) are never filtered.
+ */
+export declare const LIST_FIELDS_PARAM: {
+    type: "array";
+    items: {
+        type: "string";
+    };
+    description: string;
+};
+export declare function parseListFields(raw: unknown): string[] | undefined;
+export declare function pickListedRow(row: Record<string, unknown>, fields: string[] | undefined): Record<string, unknown>;
+export declare function pickListedRows(rows: unknown[], fields: string[] | undefined): unknown[];

package/dist/capabilities/listedFields.js

@@ -0,0 +1,45 @@
+/**
+ * Opt-in row projection for list tools.
+ *
+ * List endpoints return the full row by default. Pass `fields` to keep only
+ * those keys — the same shape as Linear's `list_issues`. Envelope keys
+ * (count, nextCursor, hasMore) are never filtered.
+ */
+export const LIST_FIELDS_PARAM = {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Return only these keys on each row. Omit for the full row. Keep the id you will use next (agreementId, taskId, artifactId, grantId).',
+};
+export function parseListFields(raw) {
+    if (raw == null)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error('fields must be a non-empty array of row key names');
+    }
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== 'string' || !item.trim()) {
+            throw new Error('fields entries must be non-empty strings');
+        }
+        if (!out.includes(item))
+            out.push(item);
+    }
+    return out;
+}
+export function pickListedRow(row, fields) {
+    if (!fields)
+        return row;
+    const picked = {};
+    for (const key of fields) {
+        if (key in row)
+            picked[key] = row[key];
+    }
+    return picked;
+}
+export function pickListedRows(rows, fields) {
+    if (!fields)
+        return rows;
+    return rows.map((row) => row && typeof row === 'object' && !Array.isArray(row)
+        ? pickListedRow(row, fields)
+        : row);
+}

package/dist/capabilities/marketplace.js

@@ -1,6 +1,7 @@
 import { pullOffers, pullRequests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
     const propose = env.surface === 'mcp' ? 'ziggs_agreement_request' : 'agreement_request';
@@ -77,6 +78,7 @@ export const marketplaceViewCapability = {
         },
         limit: { type: 'number', description: 'Max rows per kind (default 20)' },
         since: { type: 'string', description: 'ISO timestamp — only rows published after this' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -93,12 +95,15 @@ export const marketplaceViewCapability = {
             kind === 'offers' ? Promise.resolve([]) : pullRequests(options, creds),
             kind === 'requests' ? Promise.resolve([]) : pullOffers(options, creds),
         ]);
+        const fields = parseListFields(args['fields']);
+        const requestRows = pickListedRows(requests.map((q) => toListingRow(q, 'request')), fields);
+        const offerRows = pickListedRows(offers.map((o) => toListingRow(o, 'offer')), fields);
         return {
             ...(kind !== 'offers'
-                ? { requests: requests.map((q) => toListingRow(q, 'request')), requestCount: requests.length }
+                ? { requests: requestRows, requestCount: requests.length }
                 : {}),
             ...(kind !== 'requests'
-                ? { offers: offers.map((o) => toListingRow(o, 'offer')), offerCount: offers.length }
+                ? { offers: offerRows, offerCount: offers.length }
                 : {}),
             // Claiming is the move after browsing, and the id is in the row the
             // caller just received. The prose hint stays for the publish side, which

package/dist/capabilities/payments.js

@@ -1,10 +1,15 @@
 import { PaymentsClient } from '../http/PaymentsClient.js';
 import { rethrowWithContext, } from './types.js';
 function client(env) {
-    const { operatorKey, agentId } = env.creds;
+    // laneId too, like every other Creds-based client. Only the balance read is
+    // on this surface today, and a read does not spend — but the lane is what
+    // fences a spend to the job it was authorised in, so it is wired here rather
+    // than left for whoever brings a spending verb back to remember. Omitting it
+    // can only leave a spend unfenced; it can never widen one.
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    return new PaymentsClient(operatorKey, agentId, env.baseUrl);
+    return new PaymentsClient(operatorKey, agentId, env.baseUrl, laneId);
 }
 /**
  * Reading the balance is the whole rail on an agent surface.