@ziggs-ai/api-client 0.15.1 → 0.17.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) {
@@ -286,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/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.js

@@ -1,11 +1,11 @@
 import { ConnectionsClient } from "../http/ConnectionsClient.js";
 import { rethrowWithContext, } from "./types.js";
 function client(env) {
-    // laneId, not just the key and the agent. The lane is which engagement this
-    // wake is in, and the broker needs it to tell 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.
+    // 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");

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.

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.

package/dist/capabilities/tasks.js

@@ -1,5 +1,6 @@
 import { listTasks } from '../http/TaskClient.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 /**
  * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
  * same GET /tasks filters; assignedToMe vs assignedTo precedence then
@@ -11,8 +12,8 @@ export const listTasksCapability = {
     names: { sdk: 'task_list', mcp: 'ziggs_task_list' },
     title: 'List tasks',
     descriptions: {
-        sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
-        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
+        sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
+        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
     },
     annotation: 'read-only',
     params: {
@@ -40,6 +41,7 @@ export const listTasksCapability = {
             type: 'boolean',
             description: "Shorthand for assignedTo=<this agent's id>. Takes precedence over assignedTo when both are set.",
         },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -48,13 +50,17 @@ export const listTasksCapability = {
             ? creds.agentId
             : args['assignedTo'];
         const createdBy = args['createdByMe'] ? creds.agentId : undefined;
-        return listTasks({
+        const listed = await listTasks({
             state: args['state'],
             cursor: args['cursor'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
             assignedTo,
             ...(createdBy ? { createdBy } : {}),
         }, creds);
+        const fields = parseListFields(args['fields']);
+        return fields
+            ? { ...listed, tasks: pickListedRows(listed.tasks, fields) }
+            : listed;
     },
 };
 export const TASK_CAPABILITIES = [listTasksCapability];

package/dist/http/AgreementClient.js

@@ -2,22 +2,15 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 // Lazy: read at call time so a `configureApiClient` call that lands after this
 // module is imported still takes effect. Baking it at module-load time would
 // freeze the URL before the host has configured one.
 function getAgreementBaseUrl() {
     return `${getBackendUrl()}/agreements`;
 }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/ArtifactsClient.d.ts

@@ -28,6 +28,8 @@ export interface ListArtifactsResult {
 }
 export interface WriteArtifactInput {
     text: string;
+    /** Short list name. An upload defaults to filename when omitted. */
+    name?: string;
     contentType?: string;
     visibility?: ArtifactVisibility;
     /** When the artifact is associated with a chat. */
@@ -47,6 +49,8 @@ export interface WriteArtifactInput {
 }
 export type ArtifactFileFormat = 'pdf' | 'docx' | 'hwpx' | 'md' | 'txt' | 'html';
 export interface ArtifactUploadUrlInput {
+    /** Short list name. Defaults to filename on the server when omitted. */
+    name?: string;
     filename: string;
     mime: string;
     /** Exact UTF-8 / file byte length of the object that will be PUT. */
@@ -82,22 +86,7 @@ export type ArtifactFileView = Record<string, unknown> & {
     extractionError?: string | null;
     filename?: string | null;
 };
-/**
- * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
- * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
- * they persist, are searchable, but are not visible to other chat parties.
- */
-/**
- * turn a runtime lane id into a scope the backend can accept.
- *
- * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
- * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
- * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
- * thought on an agreement lane come back 403 "not authorized for this scope" —
- * a fictional scope reading like an auth failure. The work is agreement-scoped,
- * so say so; same rule settled for deliverables.
- */
-export declare const AGREEMENT_LANE_PREFIX = "agrn-";
+export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
 export declare function artifactScopeForSession(sessionId: string): {
     chatId: string;
 } | {

package/dist/http/ArtifactsClient.js

@@ -33,17 +33,18 @@ function resolveUploadBytes(input) {
  * turn a runtime lane id into a scope the backend can accept.
  *
  * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
- * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * Agent.laneSessionIdForTask). That is a routing key, not a chat: no such
  * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
  * thought on an agreement lane come back 403 "not authorized for this scope" —
  * a fictional scope reading like an auth failure. The work is agreement-scoped,
  * so say so; same rule settled for deliverables.
  */
-export const AGREEMENT_LANE_PREFIX = 'agrn-';
+import { agreementIdFromLane } from '@ziggs-ai/contracts';
+export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
 export function artifactScopeForSession(sessionId) {
-    if (sessionId.startsWith(AGREEMENT_LANE_PREFIX)) {
-        return { agreementId: sessionId.slice(AGREEMENT_LANE_PREFIX.length) };
-    }
+    const agreementId = agreementIdFromLane(sessionId);
+    if (agreementId)
+        return { agreementId };
     return { chatId: sessionId };
 }
 export class ArtifactsClient {
@@ -145,6 +146,7 @@ export class ArtifactsClient {
             headers: this._headers(),
             body: JSON.stringify({
                 text,
+                ...(input.name?.trim() ? { name: input.name.trim() } : {}),
                 contentType: input.contentType ?? 'text',
                 visibility: input.visibility ?? 'chat',
                 chatId: input.chatId,
@@ -214,6 +216,7 @@ export class ArtifactsClient {
         }
         const parsed = await this._post('/artifacts/upload-url', {
             filename: input.filename.trim(),
+            ...(input.name?.trim() ? { name: input.name.trim() } : {}),
             mime: input.mime.trim(),
             byteSize: input.byteSize,
             format: input.format,

package/dist/http/ChatClient.d.ts

@@ -1,3 +1,4 @@
+import type { SendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
 /** Shape of GET /chats/mine items — the backend's ChatReadDto. */
 export interface ChatSummary {
@@ -41,12 +42,7 @@ export interface SendChatMessageInput {
     contentType?: string;
     underAgreementId?: string;
 }
-export interface SendChatMessageResult {
-    success: boolean;
-    message: string;
-    messageId: string;
-    chatId: string;
-}
+export type { SendChatMessageResult } from '@ziggs-ai/contracts';
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface AddChatMemberInput {
     chatId: string;

package/dist/http/ChatClient.js

@@ -1,16 +1,9 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+import { buildCredsHeaders } from './operatorHeaders.js';
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/ConnectionsClient.d.ts

@@ -59,10 +59,12 @@ export declare class ConnectionsClient {
     private readonly laneId?;
     /**
      * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
-     *   an agent that serves several hirers holds all of their grants at once, so
-     *   without a lane one hirer's grant is indistinguishable from another's, and
-     *   a grant issued for one job can be spent inside a different one.
+     *   X-Ziggs-Lane. It tells the broker which hire this wake is in, and the
+     *   broker reads off it WHO the agent is acting for: an agent that serves
+     *   several hirers holds all of their grants at once and is the holder of
+     *   every one, so without a lane one hirer's grant is indistinguishable from
+     *   another's, and a grant one customer gave can be spent while working for
+     *   somebody else.
      *   ArtifactsClient sends the same header for the same reason.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);

package/dist/http/ConnectionsClient.js

@@ -37,10 +37,12 @@ export class ConnectionsClient {
     laneId;
     /**
      * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
-     *   an agent that serves several hirers holds all of their grants at once, so
-     *   without a lane one hirer's grant is indistinguishable from another's, and
-     *   a grant issued for one job can be spent inside a different one.
+     *   X-Ziggs-Lane. It tells the broker which hire this wake is in, and the
+     *   broker reads off it WHO the agent is acting for: an agent that serves
+     *   several hirers holds all of their grants at once and is the holder of
+     *   every one, so without a lane one hirer's grant is indistinguishable from
+     *   another's, and a grant one customer gave can be spent while working for
+     *   somebody else.
      *   ArtifactsClient sends the same header for the same reason.
      */
     constructor(operatorKey, agentId, baseUrl, laneId) {
@@ -101,7 +103,7 @@ export class ConnectionsClient {
      * defensively for leaked secrets, as `proxy` does.
      */
     async listForHolder() {
-        const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
+        const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl, this.laneId);
         // All pages of the agent's live connection grants (not just the first page).
         const { items, unreadableRails } = await grantsClient.listAllGrantsWithRails({
             scopeKind: "connection",

package/dist/http/ContextReadClient.js

@@ -1,5 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 export const CONTEXT_READ_TYPES = [
     'messages',
     'artifacts',
@@ -92,13 +93,7 @@ export class ContextReadClient {
         if (query.contextGrantId) {
             url.searchParams.set('contextGrantId', query.contextGrantId);
         }
-        const headers = {
-            Authorization: `Bearer ${this.operatorKey}`,
-        };
-        if (this.agentId)
-            headers['X-Agent-Id'] = this.agentId;
-        if (this.laneId)
-            headers['X-Ziggs-Lane'] = this.laneId;
+        const headers = buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId);
         if (query.contextGrantId) {
             headers['X-Context-Grant-Id'] = query.contextGrantId;
         }
@@ -131,13 +126,7 @@ export class ContextReadClient {
         if (opts.contextGrantId) {
             url.searchParams.set('contextGrantId', opts.contextGrantId);
         }
-        const headers = {
-            Authorization: `Bearer ${this.operatorKey}`,
-        };
-        if (this.agentId)
-            headers['X-Agent-Id'] = this.agentId;
-        if (this.laneId)
-            headers['X-Ziggs-Lane'] = this.laneId;
+        const headers = buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId);
         if (opts.contextGrantId) {
             headers['X-Context-Grant-Id'] = opts.contextGrantId;
         }