@ziggs-ai/api-client 0.38.2 → 0.39.0

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;
@@ -60,7 +62,7 @@ export interface IntroductionView {
         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;
@@ -89,7 +91,7 @@ export interface MintIntroductionInput {
     note?: string;
     /** What the token is about: a listing, request or proposal (agreement), a task, or a chat you hold. */
     about?: {
-        kind: 'agreement' | 'task' | 'chat' | 'workspace';
+        kind: 'agreement' | 'task' | 'address' | 'workspace';
         id: string;
     };
     /** How many people it serves, 1 to 25. Your own sessions never use one up. */

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';

package/dist/http/MessageRecordsClient.js

@@ -0,0 +1,30 @@
+import { parseMessageCommand } from '@ziggs-ai/contracts';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
+/** One command and one representation, independent of navigation. */
+export class MessageRecordsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, init = {}) { const res = await fetch(`${this.baseUrl ?? getBackendUrl()}/messaging/${path}`, { ...init, headers: { 'content-type': 'application/json', ...buildOperatorHeaders(this.operatorKey, this.agentId) } }); if (!res.ok)
+        throwApiError(res, await res.text().catch(() => ''), `Messaging failed: ${res.status}`); return await res.json(); }
+    async get(id) { const row = await this.request(`messages/${encodeURIComponent(id)}`); if (row.messageId !== id || !row.content || !Array.isArray(row.requestedAnswers))
+        throw new Error('Invalid exact message response'); return row; }
+    async send(command) { const result = await this.request('messages', { method: 'POST', body: JSON.stringify(parseMessageCommand(command)) }); if (!['created', 'existing'].includes(result.outcome) || !result.message?.messageId || !result.message.content || !Array.isArray(result.message.recipients) || !Array.isArray(result.message.requestedAnswers))
+        throw new Error('Invalid message command response'); return result; }
+    list(input = {}) { const query = new URLSearchParams(); for (const [key, value] of Object.entries(input))
+        if (value !== undefined)
+            query.set(key, Array.isArray(value) ? value.join(',') : String(value)); return this.request(`messages?${query}`); }
+    replies(id, input = {}) { const query = new URLSearchParams(); for (const [key, value] of Object.entries(input))
+        if (value !== undefined)
+            query.set(key, String(value)); return this.request(`messages/${encodeURIComponent(id)}/replies?${query}`); }
+    controls(agreementId, taskId) { const query = new URLSearchParams({ agreementId, ...(taskId ? { taskId } : {}) }); return this.request(`controls?${query}`); }
+    answers(id) { return this.request(`messages/${encodeURIComponent(id)}/answers`); }
+    cancelAnswer(id, requestId) { return this.request(`messages/${encodeURIComponent(id)}/answers/${encodeURIComponent(requestId)}/cancel`, { method: 'POST' }); }
+}

package/dist/http/SessionsClient.d.ts

@@ -8,11 +8,11 @@ export interface AssistantSessionRow {
     lastSeenAt: string;
     expiresAt: string;
     workspaceIds: string[];
-    heldChatIds: string[];
+    heldExecutionIds: string[];
     awake: boolean;
 }
 /**
- * List sibling windows and hold a chat in this one.
+ * List sibling windows and hold an execution in this one.
  * Uses the same session headers as the inbox so "this window" is the
  * X-Ziggs-Session the host already sends.
  */
@@ -23,12 +23,12 @@ export declare class SessionsClient {
     private url;
     list(): Promise<AssistantSessionRow[]>;
     /**
-     * Hold `chatId` in this window (omit sessionId; server resolves from
+     * Hold `executionContextId` in this window (omit sessionId; server resolves from
      * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
      */
-    hold(chatId: string, sessionId?: string | null): Promise<{
+    hold(executionContextId: string, sessionId?: string | null): Promise<{
         success: true;
-        chatId: string;
+        executionContextId: string;
         sessionId: string | null;
     }>;
 }

package/dist/http/SessionsClient.js

@@ -2,7 +2,7 @@ import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
 import { buildCredsHeaders } from './operatorHeaders.js';
 /**
- * List sibling windows and hold a chat in this one.
+ * List sibling windows and hold an execution in this one.
  * Uses the same session headers as the inbox so "this window" is the
  * X-Ziggs-Session the host already sends.
  */
@@ -48,14 +48,14 @@ export class SessionsClient {
         return Array.isArray(rows) ? rows : [];
     }
     /**
-     * Hold `chatId` in this window (omit sessionId; server resolves from
+     * Hold `executionContextId` in this window (omit sessionId; server resolves from
      * X-Ziggs-Session), move it to `sessionId`, or pass null to release.
      */
-    async hold(chatId, sessionId) {
-        if (!chatId?.trim())
-            throw new Error('SessionsClient.hold: chatId is required');
+    async hold(executionContextId, sessionId) {
+        if (!executionContextId?.trim())
+            throw new Error('SessionsClient.hold: executionContextId is required');
         const body = {
-            chatId: chatId.trim(),
+            executionContextId: executionContextId.trim(),
         };
         if (sessionId !== undefined)
             body.sessionId = sessionId;

package/dist/http/TaskClient.d.ts

@@ -1,3 +1,5 @@
+import { type TaskUpdateState } from '@ziggs-ai/contracts';
+export type { TaskUpdateState } from '@ziggs-ai/contracts';
 import type { WriteSource } from '../capabilities/sources.js';
 import { type Creds, type Task, type TaskState } from '../types.js';
 /**
@@ -5,6 +7,8 @@ import { type Creds, type Task, type TaskState } from '../types.js';
  * getTask / ziggs_task_get.
  */
 export interface TaskWriteConfirm {
+    success: true;
+    /** @deprecated Use success. */
     ok: true;
     taskId: string;
     /** The agreement the task hangs under, when the server reports it. */
@@ -152,9 +156,8 @@ export interface UpdateTaskStateData {
     /** What the result drew on. Recorded only when a result is written. */
     sources?: WriteSource[];
 }
-export declare function updateTaskState(taskId: string, state: TaskState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<TaskWriteConfirm>;
+export declare function updateTaskState(taskId: string, state: TaskUpdateState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function getActiveTasksForAgent(agentId: string, creds: Creds): Promise<Task[]>;
-export declare function getActiveTasksForChat(chatId: string, creds: Creds): Promise<Task[]>;
 export declare function cancelTask(taskId: string, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function getSubtasks(parentTaskId: string, creds: Creds): Promise<Task[]>;
 export interface PlanReplaceStep {
@@ -205,6 +208,8 @@ export interface ListTasksOptions {
     limit?: number;
     /** Filter to tasks assigned to this id. */
     assignedTo?: string;
+    /** Stored assignee, including tasks held by dependencies. */
+    assigneeId?: string;
     /**
      * Filter to tasks CREATED by this id — what the caller handed out, as
      * opposed to what was handed to it.
@@ -213,12 +218,14 @@ export interface ListTasksOptions {
 }
 export interface ListTasksResult {
     tasks: Task[];
+    /** Number of tasks on this page, not a total across pages. */
+    count: number;
     hasMore: boolean;
     nextCursor?: string | null;
 }
 export declare function listTasks(options: ListTasksOptions | undefined, creds: Creds): Promise<ListTasksResult>;
 export interface CountTasksFilters {
-    chatId?: string;
+    agreementId?: string;
     state?: string;
     userId?: string;
     agentId?: string;
@@ -237,9 +244,8 @@ export declare class TaskClient {
         children?: CreatedTaskChild[];
     }>;
     getTask(taskId: string): Promise<Task>;
-    updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<TaskWriteConfirm>;
+    updateTaskState(taskId: string, state: TaskUpdateState, data?: UpdateTaskStateData): Promise<TaskWriteConfirm>;
     getActiveTasksForAgent(agentId: string): Promise<Task[]>;
-    getActiveTasksForChat(chatId: string): Promise<Task[]>;
     cancelTask(taskId: string): Promise<TaskWriteConfirm>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<TaskWriteConfirm>;

package/dist/http/TaskClient.js

@@ -1,3 +1,4 @@
+import { TASK_UPDATE_STATES } from '@ziggs-ai/contracts';
 import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { partyActorIds } from '../types.js';
@@ -59,6 +60,7 @@ function extractWriteConfirm(data) {
         d['task'] === undefined &&
         d['description'] === undefined) {
         return {
+            success: true,
             ok: true,
             ...(d['control'] ? { control: d['control'] } : {}),
             taskId: d['taskId'],
@@ -86,6 +88,7 @@ function extractWriteConfirm(data) {
     if (!task?.taskId || !task.state)
         return null;
     return {
+        success: true,
         ok: true,
         taskId: task.taskId,
         state: task.state,
@@ -142,6 +145,9 @@ export async function updateTaskState(taskId, state, data = {}, creds) {
         throw new Error('updateTaskState: taskId is required');
     if (!state)
         throw new Error('updateTaskState: state is required');
+    if (!TASK_UPDATE_STATES.includes(state)) {
+        throw new Error('updateTaskState accepts active, completed or failed; use cancelTask to cancel');
+    }
     assertCreds(creds, 'task state update');
     const res = await fetch(`${getTaskBaseUrl()}/${taskId}/state`, {
         method: 'PATCH',
@@ -219,37 +225,6 @@ async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
     const merged = lists.flat();
     return workable(merged.filter((t) => !t.assigneeId || t.assigneeId === agentId));
 }
-// Backend deliberately has no `/chats/:id/tasks` route — it's composable
-// from links → per-agreement tasks. We do the composition here so callers
-// don't have to.
-export async function getActiveTasksForChat(chatId, creds) {
-    if (!chatId)
-        throw new Error('getActiveTasksForChat: chatId is required');
-    assertCreds(creds, 'getting active tasks for chat');
-    const linksRes = await fetch(`${getBackendUrl()}/agreements/by-chat/${encodeURIComponent(chatId)}`, { method: 'GET', headers: buildHeaders(creds) });
-    if (!linksRes.ok) {
-        const body = await linksRes.text().catch(() => '');
-        throwApiError(linksRes, body, `Get agreements for chat failed: ${linksRes.status} ${linksRes.statusText}`);
-    }
-    const linksData = await linksRes.json().catch(() => null);
-    const rawLinks = linksData?.['links'] ?? linksData?.['agreements'];
-    const agreements = Array.isArray(rawLinks) ? rawLinks : [];
-    const agreementIds = Array.from(new Set(agreements.map((a) => a['agreementId']).filter(Boolean)));
-    if (agreementIds.length === 0)
-        return [];
-    const lists = await Promise.all(agreementIds.map(async (aid) => {
-        const url = new URL(`${getBackendUrl()}/agreements/${encodeURIComponent(aid)}/tasks`);
-        url.searchParams.set('state', 'active');
-        const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            throwApiError(res, body, `Get tasks for agreement ${aid} failed: ${res.status}`);
-        }
-        const data = await res.json().catch(() => null);
-        return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
-    }));
-    return lists.flat();
-}
 export async function cancelTask(taskId, creds) {
     if (!taskId)
         throw new Error('cancelTask: taskId is required');
@@ -426,6 +401,8 @@ export async function listTasks(options = {}, creds) {
         url.searchParams.set('limit', String(options.limit));
     if (options.assignedTo)
         url.searchParams.set('assignedTo', options.assignedTo);
+    if (options.assigneeId)
+        url.searchParams.set('assigneeId', options.assigneeId);
     if (options.createdBy)
         url.searchParams.set('createdBy', options.createdBy);
     const res = await fetch(url.toString(), {
@@ -440,6 +417,7 @@ export async function listTasks(options = {}, creds) {
     const tasks = Array.isArray(data?.['tasks']) ? data['tasks'] : [];
     return {
         tasks,
+        count: tasks.length,
         hasMore: Boolean(data?.['hasMore']),
         nextCursor: data?.['nextCursor'] ?? null,
     };
@@ -448,8 +426,8 @@ export async function countTasks(filters = {}, creds) {
     assertCreds(creds, 'count tasks');
     // Canonical REST: GET /tasks/count.
     const url = new URL(`${getTaskBaseUrl()}/count`);
-    if (filters.chatId)
-        url.searchParams.set('chatId', filters.chatId);
+    if (filters.agreementId)
+        url.searchParams.set('agreementId', filters.agreementId);
     if (filters.state)
         url.searchParams.set('state', filters.state);
     if (filters.userId)
@@ -489,7 +467,6 @@ export class TaskClient {
     getTask(taskId) { return getTask(taskId, this.creds); }
     updateTaskState(taskId, state, data) { return updateTaskState(taskId, state, data ?? {}, this.creds); }
     getActiveTasksForAgent(agentId) { return getActiveTasksForAgent(agentId, this.creds); }
-    getActiveTasksForChat(chatId) { return getActiveTasksForChat(chatId, this.creds); }
     cancelTask(taskId) { return cancelTask(taskId, this.creds); }
     getSubtasks(parentTaskId) { return getSubtasks(parentTaskId, this.creds); }
     replaceTaskPlan(taskId, steps) { return replaceTaskPlan(taskId, steps, this.creds); }