@ziggs-ai/api-client 0.38.0 → 0.39.0

package/dist/http/ConnectionsClient.js

@@ -161,13 +161,15 @@ export class ConnectionsClient {
     /**
      * agent-initiated MCP connection request: ask the principal to
      * connect a remote MCP server and grant this agent the listed tools. Opens a
-     * connection-consent agreement in the working chat; on approval the
+     * connection-consent agreement for explicit work/message context; on approval the
      * server is connected (if needed) and the agent is granted the tools.
      */
-    async requestMcpConnection({ serverUrl, tools, reason, chatId, recipientId, onBehalfOfUserId, }) {
+    async requestMcpConnection({ serverUrl, tools, reason, context, recipientId, onBehalfOfUserId, }) {
         if (!serverUrl)
             throw new Error("requestMcpConnection: serverUrl is required");
-        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, chatId, ...(recipientId ? { recipientId } : {}) }, onBehalfOfUserId
+        if (!context || !["message", "task", "agreement"].includes(context.kind) || !context.id)
+            throw new Error("requestMcpConnection: context is required");
+        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, context, ...(recipientId ? { recipientId } : {}) }, onBehalfOfUserId
             ? { "X-On-Behalf-Of-User": onBehalfOfUserId }
             : undefined));
     }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -4,10 +4,10 @@
  * provider name only (never tokens/account labels).
  */
 export interface DiscoverableItem {
-    type: 'chat' | 'agreement' | 'connection';
+    type: 'address' | 'agreement' | 'connection';
     label: string;
     scopeRef: {
-        kind: 'chat' | 'agreement' | 'org' | 'connection';
+        kind: 'address' | 'agreement' | 'org' | 'connection';
         id: string;
     };
     orgId: string;

package/dist/http/ContextGrantsClient.d.ts

@@ -69,18 +69,16 @@ export interface ReachEntry {
     label: string;
 }
 /**
- * reach expansion — the chat/agreement ids a grant you hold actually
+ * Reach expansion — the agreement ids a grant you hold actually
  * covers, so an org/agreement-scoped grant becomes a concrete list you can
- * `context_read` through (via=chat:<id> / agreement:<id>). Ids + labels only,
- * never content. Org scope is capped; `truncatedChats`/`truncatedAgreements`
- * report how many were left off, never silently dropped.
+ * inspect using the retained resource operations. Ids + labels only,
+ * never content. Org scope is capped; `truncatedAgreements`
+ * reports how many were left off.
  */
 export interface GrantReachResult {
     grantId: string;
     scope: ContextGrantScope;
-    chats: ReachEntry[];
     agreements: ReachEntry[];
-    truncatedChats: number;
     truncatedAgreements: number;
 }
 /**
@@ -98,20 +96,20 @@ export declare class ContextGrantsClient {
     issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
     /** Request-only endpoint: a successful call must still have granted no access. */
     requestAccess(input: {
-        scopeKind: 'artifact' | 'chat' | 'agreement' | 'task' | 'person';
+        scopeKind: 'message' | 'artifact' | 'address' | 'agreement' | 'task' | 'person';
         scopeId?: string;
         agreementId?: string;
         reason: string;
         permission?: 'read' | 'reply' | 'work' | 'list';
         temporal?: 'from-now' | 'from-start';
         durationHours?: number;
-        chatId?: string;
         ownerId?: string;
         /** Who to ask, from the people the server offers this wake. */
         recipientId?: string;
         /** Artifact only: who should read it, if not only the caller. One grant each. */
         holders?: AccessReader[];
         contributionTo?: import('@ziggs-ai/contracts').ContributionTarget;
+        releaseSource?: import('@ziggs-ai/contracts').ContributionSource;
     }, opts?: {
         idempotencyKey?: string;
         laneId?: string;
@@ -120,9 +118,9 @@ export declare class ContextGrantsClient {
         idempotencyKey?: string;
     }): Promise<DelegateContextGrantResult>;
     /**
-     * expand a grant you hold into the chat/agreement ids inside its
+     * Expand a grant you hold into the agreement ids inside its
      * scope. A grant is a fence, not a listing: discovery says "you hold
-     * org:acme", this says which chats/agreements that covers. Holder-only,
+     * org:acme", this says which agreements that covers. Holder-only,
      * labels-only, grant-fenced server-side.
      */
     getReach(grantId: string): Promise<GrantReachResult>;
@@ -139,7 +137,6 @@ export declare class ContextGrantsClient {
     shareArtifact(artifactId: string, input: {
         holderId: string;
         expiresAt?: string | null;
-        chatId?: string;
     }, opts?: {
         idempotencyKey?: string;
     }): Promise<DelegateContextGrantResult>;
@@ -181,11 +178,8 @@ export interface RequestSentTo {
         role: 'customer' | 'operator';
     };
     approveIn?: {
-        kind: 'chat';
-        chatId: string;
-    } | {
         kind: 'inbox';
     };
-    /** e.g. "Sent to Ido. Ido approves it in this room." */
+    /** Human-readable approval destination. */
     message?: string;
 }

package/dist/http/ContextGrantsClient.js

@@ -114,9 +114,9 @@ export class ContextGrantsClient {
         return parseGrantOrPending(body, 'POST /context/grants/:id/delegate');
     }
     /**
-     * expand a grant you hold into the chat/agreement ids inside its
+     * Expand a grant you hold into the agreement ids inside its
      * scope. A grant is a fence, not a listing: discovery says "you hold
-     * org:acme", this says which chats/agreements that covers. Holder-only,
+     * org:acme", this says which agreements that covers. Holder-only,
      * labels-only, grant-fenced server-side.
      */
     async getReach(grantId) {
@@ -127,14 +127,12 @@ export class ContextGrantsClient {
         }
         const parsed = JSON.parse(body);
         if (!parsed.scope) {
-            throw new Error('Invalid response: expected { scope, chats, agreements } from GET /context/grants/:id/reach');
+            throw new Error('Invalid response: expected { scope, agreements } from GET /context/grants/:id/reach');
         }
         return {
             grantId: parsed.grantId ?? grantId,
             scope: parsed.scope,
-            chats: parsed.chats ?? [],
             agreements: parsed.agreements ?? [],
-            truncatedChats: parsed.truncatedChats ?? 0,
             truncatedAgreements: parsed.truncatedAgreements ?? 0,
         };
     }

package/dist/http/ContextOpenClient.d.ts

@@ -1,4 +1,4 @@
-export declare const CONTEXT_OPEN_KINDS: readonly ["artifact", "chat", "task", "agreement"];
+export declare const CONTEXT_OPEN_KINDS: readonly ["artifact", "task", "agreement"];
 export type ContextOpenKind = (typeof CONTEXT_OPEN_KINDS)[number];
 export type ContextOpenOutcome = 'ok' | 'unreadable' | 'hidden';
 export interface ContextOpenRef {
@@ -6,10 +6,9 @@ export interface ContextOpenRef {
     id: string;
 }
 export interface ContextOpenBody {
-    /** A handle (T…/A…/C…/F…), a Ziggs URL holding one, or an older id. */
+    /** A handle (T…/A…/F…), a Ziggs URL holding one, or an older id. */
     ref?: string;
     artifactId?: string;
-    chatId?: string;
     taskId?: string;
     agreementId?: string;
     cursor?: string;
@@ -50,10 +49,10 @@ export interface ContextOpenAccess {
         kind: 'owner_decision';
         summary: string;
         request?: {
-            scopeKind: 'chat' | 'agreement' | 'task';
+            scopeKind: 'agreement' | 'task';
             scopeId: string;
-            permission: 'read' | 'reply';
-            temporal: 'from-now' | 'from-start';
+            permission: 'read';
+            temporal: 'from-start';
             durationHours: number;
         };
     };

package/dist/http/ContextOpenClient.js

@@ -4,7 +4,6 @@ import { pollSurfaceError } from '../shared/rateLimit.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 export const CONTEXT_OPEN_KINDS = [
     'artifact',
-    'chat',
     'task',
     'agreement',
 ];
@@ -43,21 +42,29 @@ export class ContextOpenClient {
         if (!res.ok) {
             throw pollSurfaceError(`ContextOpenClient ${path}`, res, text);
         }
-        return JSON.parse(text);
+        const result = JSON.parse(text);
+        if (result?.ref?.kind === 'address') {
+            throw Object.assign(new Error('Room references are retired; select an exact artifact, task or agreement'), { code: 'INVALID_INPUT' });
+        }
+        return result;
     }
 }
 export function normalizeContextOpenBody(args) {
     // A mistyped handle is refused here, before any call: its check letter
     // fails. Any other id goes to the server, which knows older shapes.
     const invalid = (message) => Object.assign(new Error(message), { code: 'INVALID_INPUT' });
-    const keys = ['ref', 'artifactId', 'chatId', 'taskId', 'agreementId'].filter(key => args[key] !== undefined);
+    if ('addressId' in args)
+        throw invalid('addressId is retired; select an exact artifact, task or agreement');
+    const keys = ['ref', 'artifactId', 'taskId', 'agreementId'].filter(key => args[key] !== undefined);
     if (keys.length !== 1)
-        throw invalid('Pass exactly one resource reference: ref, artifactId, chatId, taskId, or agreementId');
+        throw invalid('Pass exactly one resource reference: ref, artifactId, taskId, or agreementId');
     const key = keys[0];
     const raw = typeof args[key] === 'string' ? args[key].trim() : '';
     if (!raw)
         throw invalid(`${key} must be a non-empty resource reference`);
     const ref = parseRef(raw);
+    if (ref?.kind === 'address' || /^(?:address|chat):/.test(raw))
+        throw invalid('Room references are retired; select an exact artifact, task or agreement');
     if (!ref && looksLikeHandle(raw))
         throw invalid(`${raw} is not a handle: its check letter does not match. Check it for a typo`);
     const body = { [key]: ref?.id ?? raw };

package/dist/http/ContextReadClient.d.ts

@@ -1,23 +1,23 @@
-export declare const CONTEXT_READ_TYPES: readonly ["messages", "artifacts", "agreements", "tasks"];
+export declare const CONTEXT_READ_TYPES: readonly ["artifacts", "agreements", "tasks"];
 export type ContextReadType = (typeof CONTEXT_READ_TYPES)[number];
 /**
- * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
- * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
- * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ * Retained resource entry points for context reads and snapshots.
+ * The server still accepts legacy room entries until coordinated removal;
+ * new callers use only the domain resources below.
  */
-export declare const VIA_KINDS: readonly ["chat", "agreement", "task", "counterparty", "artifact"];
+export declare const VIA_KINDS: readonly ["agreement", "task", "artifact", "message"];
 export type ViaKind = (typeof VIA_KINDS)[number];
 /**
- * Which entry points each read type actually accepts, mirroring the server's
+ * Which entry points each read type actually accepts, using the retained subset of the server's
  * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
  * check, and this type all read off the same list instead of three prose
  * copies that drift — and so a wrong pairing is refused with the reason rather
  * than as a bare 400 from a round-trip away.
  */
 export declare const CONTEXT_READ_VIA: Record<ContextReadType, readonly ViaKind[]>;
-/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+/** `agreement:<id>, task:<id>` — the accepted entries for one read type, for humans. */
 export declare function viaHint(type: ContextReadType): string;
-/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+/** Split `agreement:abc` into its parts, or null when it is not a `via` at all. */
 export declare function parseVia(via: string): {
     kind: ViaKind;
     id: string;
@@ -43,7 +43,7 @@ export interface ContextReadEnvelope<T = unknown> {
     nextCursor: string | null;
     latestSequence?: string | null;
 }
-/** Aggregated chat snapshot from `GET /context/snapshot` (follow-up). */
+/** Authorized resource snapshot from `GET /context/snapshot`. */
 /**
  * One participant on the snapshot roster. `kind` is the declared holder kind the
  * server stamped on the row, so a reader takes what a participant IS from the
@@ -56,6 +56,14 @@ export interface ContextSnapshotParticipant {
     isYou?: boolean;
     [key: string]: unknown;
 }
+export interface ContextSnapshotQuery {
+    /** Exact message, task, agreement, or artifact entry; no implicit room. */
+    via: string;
+    agreementId?: string;
+    artifactId?: string;
+    maxMessages?: number;
+    contextGrantId?: string;
+}
 export interface ContextSnapshotResult {
     /** Server-resolved orientation; writes recheck authority. */
     workBrief?: Record<string, unknown> & {
@@ -64,14 +72,14 @@ export interface ContextSnapshotResult {
     work?: Record<string, unknown>;
     history: unknown[];
     agreements: unknown[];
-    /** Bounded room inventory, without bodies. Absent on older backends. */
+    /** Bounded authorized artifact inventory, without bodies. */
     artifacts?: ContextReadEnvelope<{
         artifactId: string;
         name: string | null;
         contentType: string;
         timestamp: string | null;
     }>;
-    /** Direct artifact grants missing from the room inventory. Id and name only. */
+    /** Direct artifact grants outside the selected work inventory. Id and name only. */
     grantedArtifacts?: {
         items: Array<{
             artifactId: string;
@@ -87,11 +95,10 @@ export interface ContextSnapshotResult {
         userId: string;
     }>;
     latestSequence?: string | null;
-    chatMissing?: boolean;
 }
 /**
  * Protocol-first uniform context reads.
- * Wraps `GET /context/read/:type` — one client, one envelope, four types.
+ * Wraps `GET /context/read/:type` — one client, one envelope, three types.
  */
 export declare class ContextReadClient {
     private readonly operatorKey;
@@ -100,18 +107,7 @@ export declare class ContextReadClient {
     /** Authority is supplied by withWorkExecution / withWorkExecutionId. */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
-    /**
-     * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
-     * server composes history + agreements + roster through the same grant-fenced
-     * readers as {@link read}, so hosted agents pull one fenced view per poll cycle.
-     * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
-     */
-    snapshot(chatId: string, opts?: {
-        maxMessages?: number;
-        contextGrantId?: string;
-        agreementId?: string;
-        taskId?: string;
-        artifactId?: string;
-        via?: string;
-    }): Promise<ContextSnapshotResult>;
+    /** A snapshot selects one domain resource; the current execution headers
+     * remain authoritative and are never cleared after a refusal. */
+    snapshot(opts: ContextSnapshotQuery): Promise<ContextSnapshotResult>;
 }

package/dist/http/ContextReadClient.js

@@ -2,41 +2,38 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 export const CONTEXT_READ_TYPES = [
-    'messages',
     'artifacts',
     'agreements',
     'tasks',
 ];
 /**
- * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
- * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
- * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ * Retained resource entry points for context reads and snapshots.
+ * The server still accepts legacy room entries until coordinated removal;
+ * new callers use only the domain resources below.
  */
 export const VIA_KINDS = [
-    'chat',
     'agreement',
     'task',
-    'counterparty',
     'artifact',
+    'message',
 ];
 /**
- * Which entry points each read type actually accepts, mirroring the server's
+ * Which entry points each read type actually accepts, using the retained subset of the server's
  * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
  * check, and this type all read off the same list instead of three prose
  * copies that drift — and so a wrong pairing is refused with the reason rather
  * than as a bare 400 from a round-trip away.
  */
 export const CONTEXT_READ_VIA = {
-    messages: ['chat'],
-    artifacts: ['chat', 'agreement', 'task', 'artifact'],
-    agreements: ['chat', 'agreement'],
+    artifacts: ['agreement', 'task', 'artifact'],
+    agreements: ['agreement'],
     tasks: ['agreement', 'task'],
 };
-/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+/** `agreement:<id>, task:<id>` — the accepted entries for one read type, for humans. */
 export function viaHint(type) {
     return CONTEXT_READ_VIA[type].map((k) => `${k}:<id>`).join(', ');
 }
-/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+/** Split `agreement:abc` into its parts, or null when it is not a `via` at all. */
 export function parseVia(via) {
     const at = via.indexOf(':');
     if (at <= 0)
@@ -51,7 +48,7 @@ export function parseVia(via) {
 }
 /**
  * Protocol-first uniform context reads.
- * Wraps `GET /context/read/:type` — one client, one envelope, four types.
+ * Wraps `GET /context/read/:type` — one client, one envelope, three types.
  */
 export class ContextReadClient {
     operatorKey;
@@ -69,6 +66,10 @@ export class ContextReadClient {
         if (!query.via?.trim()) {
             throw new Error('ContextReadClient.read: via is required');
         }
+        const parsed = parseVia(query.via.trim());
+        if (!parsed || !CONTEXT_READ_VIA[type]?.includes(parsed.kind)) {
+            throw new Error(`ContextReadClient.read: ${type} reads accept via=${CONTEXT_READ_VIA[type] ? viaHint(type) : 'a retained resource'}`);
+        }
         const url = new URL(`${this.baseUrl}/context/read/${encodeURIComponent(type)}`);
         url.searchParams.set('via', query.via.trim());
         if (query.agreementId)
@@ -101,18 +102,18 @@ export class ContextReadClient {
         }
         return JSON.parse(body);
     }
-    /**
-     * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
-     * server composes history + agreements + roster through the same grant-fenced
-     * readers as {@link read}, so hosted agents pull one fenced view per poll cycle.
-     * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
-     */
-    async snapshot(chatId, opts = {}) {
-        if (!chatId?.trim()) {
-            throw new Error('ContextReadClient.snapshot: chatId is required');
+    /** A snapshot selects one domain resource; the current execution headers
+     * remain authoritative and are never cleared after a refusal. */
+    async snapshot(opts) {
+        const via = opts?.via?.trim();
+        if (!via || !parseVia(via)) {
+            throw new Error('ContextReadClient.snapshot: an explicit resource is required (message:<id>, task:<id>, agreement:<id>, or artifact:<id>)');
+        }
+        if (parseVia(via)?.kind === 'message' && (opts.agreementId || opts.artifactId)) {
+            throw new Error('ContextReadClient.snapshot: select an exact message independently of other resources');
         }
         const url = new URL(`${this.baseUrl}/context/snapshot`);
-        url.searchParams.set('via', opts.taskId ? `task:${opts.taskId}` : opts.via ?? (chatId.startsWith('agrn-') ? `agreement:${opts.agreementId ?? chatId.slice(5)}` : `chat:${chatId}`));
+        url.searchParams.set('via', via);
         if (opts.agreementId)
             url.searchParams.set('agreementId', opts.agreementId);
         if (opts.artifactId)

package/dist/http/ExecutionContextClient.d.ts

@@ -1,3 +1,7 @@
-import type { WorkExecutionContext } from '@ziggs-ai/contracts';
+import type { ActionRef, WorkExecutionContext } from '@ziggs-ai/contracts';
 /** Fail closed before resuming model state, including timers and recorded wakes. */
 export declare function validateWorkExecution(context: WorkExecutionContext, operatorKey: string, baseUrl?: string): Promise<void>;
+/** Explicit admission, outside an existing execution. Never retries a refused context. */
+export declare function prepareWorkExecution(action: ActionRef, operatorKey: string, agentId: string, baseUrl?: string): Promise<WorkExecutionContext>;
+/** The host holds a fenced lease while it runs; release is not domain completion. */
+export declare function runWorkExecution<T>(context: WorkExecutionContext, operatorKey: string, run: (context: WorkExecutionContext) => Promise<T>, baseUrl?: string): Promise<T>;

package/dist/http/ExecutionContextClient.js

@@ -1,5 +1,5 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
-import { buildOperatorHeaders, withWorkExecution } from './operatorHeaders.js';
+import { buildOperatorHeaders, withWorkExecution, withoutExecution } from './operatorHeaders.js';
 import { throwApiError } from '../shared/apiError.js';
 /** Fail closed before resuming model state, including timers and recorded wakes. */
 export async function validateWorkExecution(context, operatorKey, baseUrl = getBackendUrl()) {
@@ -15,3 +15,50 @@ export async function validateWorkExecution(context, operatorKey, baseUrl = getB
             throw new Error('Execution preflight returned a different context');
     });
 }
+/** Explicit admission, outside an existing execution. Never retries a refused context. */
+export async function prepareWorkExecution(action, operatorKey, agentId, baseUrl = getBackendUrl()) {
+    const response = await fetch(`${baseUrl}/execution/prepare`, {
+        method: 'POST', headers: { ...buildOperatorHeaders(operatorKey, agentId), 'content-type': 'application/json' },
+        body: JSON.stringify(action),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throwApiError(response, text, 'Action execution is unavailable');
+    const context = JSON.parse(text);
+    if (!context.contextId || context.actorId !== agentId)
+        throw new Error('Invalid action execution response');
+    return context;
+}
+/** The host holds a fenced lease while it runs; release is not domain completion. */
+export async function runWorkExecution(context, operatorKey, run, baseUrl = getBackendUrl()) {
+    const call = async (body, selected = context) => withWorkExecution(selected, async () => {
+        const finish = body.operation === 'finish';
+        const headers = buildOperatorHeaders(operatorKey, context.actorId);
+        const response = await fetch(`${baseUrl}/execution/attempt`, { method: 'POST',
+            headers: { ...(finish ? withoutExecution(headers) : headers), 'content-type': 'application/json' },
+            body: JSON.stringify(finish ? { ...body, contextId: selected.contextId, attemptId: selected.attemptId } : body) });
+        const text = await response.text();
+        if (!response.ok)
+            throwApiError(response, text, 'Execution attempt refused');
+        return JSON.parse(text);
+    });
+    const attempt = await call({ operation: 'claim' });
+    if (attempt.contextId !== context.contextId || !attempt.attemptId)
+        throw new Error('Invalid execution attempt response');
+    let lost;
+    const timer = setInterval(() => { void call({ operation: 'renew' }, attempt).catch(error => { lost = error; }); }, 20_000);
+    timer.unref();
+    try {
+        const result = await withWorkExecution(attempt, () => run(attempt));
+        if (lost)
+            throw lost;
+        return result;
+    }
+    finally {
+        clearInterval(timer);
+        // A stale worker never releases its replacement. Failure here keeps durable
+        // inputs pending; it must not transform an execution refusal into a retry
+        // without its selected authority.
+        await call({ operation: 'finish' }, attempt);
+    }
+}

package/dist/http/IntroductionsClient.d.ts

@@ -6,8 +6,10 @@ export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' |
  * (your own token, a teammate's, or someone you are already linked to).
  * `claimed` / `bid` / `accepted`: the listing, request or proposal it names.
  * `link_pending`: a link both people still approve.
+ * `held`: an agent with no person around holds it as a guest until a person
+ * claims that agent; the claim finishes the redeem as them.
  */
-export type IntroductionOutcome = 'joined' | 'claimed' | 'bid' | 'accepted' | 'link_pending';
+export type IntroductionOutcome = 'joined' | 'claimed' | 'bid' | 'accepted' | 'link_pending' | 'held';
 export interface IntroductionFrom {
     orgId: string;
     agentId: string | null;
@@ -34,7 +36,7 @@ export interface IntroductionView {
     note: string | null;
     /** What the token is about. The public view gives kind and title only. */
     about?: {
-        kind: 'agreement' | 'task' | 'chat' | 'workspace';
+        kind: 'agreement' | 'task' | 'address' | 'workspace';
         id?: string;
         title: string | null;
         shape: 'listing' | 'request' | 'proposal' | null;
@@ -44,13 +46,23 @@ export interface IntroductionView {
         allowed: number;
         left: number;
     };
+    /** Ziggs emailed it, and only the person signed in with that address redeems it. */
+    addressed?: boolean;
     agreementId: string | null;
     redeemedBy: {
         agentId: string | null;
         orgId: string | null;
     } | null;
+    /** The minter's list only: each redeemer and where they ended. */
+    redemptions?: Array<{
+        agentId: string | null;
+        orgId: string | null;
+        outcome: IntroductionOutcome;
+        agreementId: string | null;
+        at: string;
+    }>;
     /** Returned to a redeemer only: the room its agent is now in. */
-    chatId?: string | null;
+    addressId?: string | null;
     expiresAt: string;
     /** The public page the string points at. This is what you hand over. */
     url: string;
@@ -77,6 +89,17 @@ export interface MintIntroductionInput {
     venue?: string;
     venueRef?: string;
     note?: string;
+    /** What the token is about: a listing, request or proposal (agreement), a task, or a chat you hold. */
+    about?: {
+        kind: 'agreement' | 'task' | 'address' | 'workspace';
+        id: string;
+    };
+    /** How many people it serves, 1 to 25. Your own sessions never use one up. */
+    redeems?: number;
+    /** A workspace string: the email it is for. Only that person redeems it. */
+    email?: string;
+    /** A workspace string: the role it gives (default member). */
+    role?: 'owner' | 'admin' | 'member';
     /** What this text drew on. See {@link WriteSource}. */
     sources?: WriteSource[];
 }
@@ -93,7 +116,13 @@ export declare class IntroductionsClient {
     private readonly baseUrl;
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     mint(input?: MintIntroductionInput): Promise<IntroductionView>;
-    redeem(token: string): Promise<IntroductionView>;
+    /**
+     * A workspace string joins only with `confirm: true`, which is the person's
+     * yes: without it the answer names the workspace and asks for that yes.
+     */
+    redeem(token: string, opts?: {
+        confirm?: boolean;
+    }): Promise<IntroductionView>;
     decline(token: string): Promise<IntroductionView>;
     revoke(token: string): Promise<IntroductionView>;
     listMine(limit?: number): Promise<IntroductionView[]>;

package/dist/http/IntroductionsClient.js

@@ -23,8 +23,12 @@ export class IntroductionsClient {
     async mint(input = {}) {
         return this.call('POST', '/introductions', input, 'mint');
     }
-    async redeem(token) {
-        return this.call('POST', `/introductions/${encodeURIComponent(token)}/redeem`, {}, 'redeem');
+    /**
+     * A workspace string joins only with `confirm: true`, which is the person's
+     * yes: without it the answer names the workspace and asks for that yes.
+     */
+    async redeem(token, opts = {}) {
+        return this.call('POST', `/introductions/${encodeURIComponent(token)}/redeem`, opts.confirm ? { confirm: true } : {}, 'redeem');
     }
     async decline(token) {
         return this.call('POST', `/introductions/${encodeURIComponent(token)}/decline`, {}, 'decline');

package/dist/http/MessageRecordsClient.d.ts

@@ -0,0 +1,36 @@
+import type { MessageCommand, MessageCommandResult, MessageRecord, MessagingControls } from '@ziggs-ai/contracts';
+export interface MessageQuery {
+    q?: string;
+    senderId?: string;
+    recipientIds?: string[];
+    agreementId?: string;
+    taskId?: string;
+    participantIds?: string[];
+    before?: string;
+    limit?: number;
+}
+export interface MessagePage {
+    messages: MessageRecord[];
+    nextCursor: string | null;
+}
+/** One command and one representation, independent of navigation. */
+export declare class MessageRecordsClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    private readonly baseUrl?;
+    constructor(operatorKey: string, agentId: string, baseUrl?: string | undefined);
+    private request;
+    get(id: string): Promise<MessageRecord>;
+    send(command: MessageCommand): Promise<MessageCommandResult>;
+    list(input?: MessageQuery): Promise<MessagePage>;
+    replies(id: string, input?: {
+        before?: string;
+        limit?: number;
+    }): Promise<MessagePage>;
+    controls(agreementId: string, taskId?: string): Promise<MessagingControls>;
+    answers(id: string): Promise<unknown>;
+    cancelAnswer(id: string, requestId: string): Promise<{
+        state: 'cancelled';
+    }>;
+}
+export type { MessageCommand, MessageCommandResult, MessageRecord } from '@ziggs-ai/contracts';