@ziggs-ai/api-client 0.1.3 → 0.1.5

package/dist/http/AgreementClient.js

@@ -0,0 +1,477 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { OPEN_AGREEMENT_TARGET, ApiError } from '../types.js';
+import { publishToLedger } from './TaskClient.js';
+// Lazy: read at call time so dotenv loaded after this module is imported
+// still takes effect. Baking it at module-load time would freeze the URL
+// before the caller's dotenv.config() runs.
+function getAgreementBaseUrl() {
+    return `${getBackendUrl()}/agreements`;
+}
+function buildHeaders(creds) {
+    return {
+        'content-type': 'application/json',
+        Authorization: `Bearer ${creds.operatorKey}`,
+        'X-Agent-Id': creds.agentId,
+    };
+}
+function assertCreds(creds, op) {
+    if (!creds?.operatorKey)
+        throw new Error(`operatorKey is required for ${op}`);
+    if (!creds?.agentId)
+        throw new Error(`agentId is required for ${op}`);
+}
+function parseErrorMessage(responseBody, defaultMessage) {
+    if (!responseBody)
+        return defaultMessage;
+    try {
+        const d = JSON.parse(responseBody);
+        return d['details'] || d['error'] || d['message'] || defaultMessage;
+    }
+    catch {
+        return responseBody || defaultMessage;
+    }
+}
+function throwApiError(response, responseBody, defaultMessage) {
+    throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
+}
+export async function proposeAgreement(proposalData, creds) {
+    if (!proposalData)
+        throw new Error('Proposal data is required for proposal creation');
+    assertCreds(creds, 'proposal creation');
+    const { idempotencyKey, ...bodyData } = proposalData;
+    const headers = buildHeaders(creds);
+    if (idempotencyKey)
+        headers['Idempotency-Key'] = idempotencyKey;
+    // ZIG-207: canonical REST path. Backend keeps /propose serving the
+    // identical handler with a Deprecation/Sunset header until PR-F removes it.
+    const res = await fetch(`${getAgreementBaseUrl()}/proposals`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(bodyData),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Proposal creation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from POST /agreements/proposals');
+    }
+    return data['agreement'];
+}
+/** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
+export async function proposeDirectTo(input, creds) {
+    return proposeAgreement(input, creds);
+}
+/** Propose an open quest (`proposedTo: "everyone"`). Server defaults `engagementKind` to `service`. */
+export async function proposeBroadcast(input, creds) {
+    return proposeAgreement({ ...input, proposedTo: OPEN_AGREEMENT_TARGET }, creds);
+}
+export async function delegateAgreement(proposalData, creds) {
+    if (!proposalData)
+        throw new Error('Proposal data is required for delegation');
+    if (!proposalData.parentAgreementId)
+        throw new Error('parentAgreementId is required for delegation');
+    assertCreds(creds, 'proposal creation');
+    const { idempotencyKey, parentAgreementId } = proposalData;
+    const headers = buildHeaders(creds);
+    if (idempotencyKey)
+        headers['Idempotency-Key'] = idempotencyKey;
+    // ZIG-207 / ZIG-270: parentAgreementId in path AND body. Backend's
+    // `DelegateTaskDto` validates `parentAgreementId` as a required string;
+    // controller (`POST /agreements/:parentAgreementId/delegations`) merges
+    // path over body, so duplicating the value is harmless. Stripping it
+    // from the body (as ZIG-207 #72 did) trips DTO validation and returns
+    // `400: parentAgreementId must be a string` → infinite retry loop in
+    // `agreement_subcontract`. Send both, let the path win.
+    const bodyWithParent = { ...proposalData };
+    delete bodyWithParent.idempotencyKey;
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(parentAgreementId)}/delegations`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(bodyWithParent),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Delegation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from POST /agreements/:parentAgreementId/delegations');
+    }
+    return data['agreement'];
+}
+export async function respondToAgreement(agreementId, action, creds) {
+    if (!agreementId || !action)
+        throw new Error('Agreement ID and action are required for proposal response');
+    assertCreds(creds, 'proposal response');
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/respond`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ action }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Proposal response failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from /agreements/:id/respond');
+    }
+    return data['agreement'];
+}
+export async function counterAgreement(agreementId, counter, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required for counter-offer');
+    assertCreds(creds, 'counter proposal');
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/counter`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(counter || {}),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Counter proposal failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from /agreements/:id/counter');
+    }
+    return data['agreement'];
+}
+export async function getAgreementStatus(agreementId, creds) {
+    if (!agreementId)
+        return null;
+    assertCreds(creds, 'proposal status read');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/status`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Proposal status read failed: ${res.status} ${res.statusText} ${body}`);
+            return null;
+        }
+        return await res.json().catch(() => null);
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Proposal status read failed: ${e.message}`);
+        return null;
+    }
+}
+export async function listAgreements(filters = {}, creds) {
+    assertCreds(creds, 'list agreements');
+    try {
+        // Canonical query path: GET /agreements?scope=&status=&engagementKind=&...
+        const url = new URL(getAgreementBaseUrl());
+        if (filters.status)
+            url.searchParams.set('status', filters.status);
+        if (filters.engagementKind)
+            url.searchParams.set('engagementKind', filters.engagementKind);
+        if (filters.proposalStatus)
+            url.searchParams.set('proposalStatus', filters.proposalStatus);
+        if (filters.hasTask != null)
+            url.searchParams.set('hasTask', String(filters.hasTask));
+        const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ List agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['agreements']) ? data['agreements'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ List agreements failed: ${e.message}`);
+        return [];
+    }
+}
+export async function getMyAgreements(filters = {}, creds) {
+    assertCreds(creds, 'get my agreements');
+    try {
+        // Canonical query path: GET /agreements?scope=mine returns the enriched
+        // shape (tasks + originChatId + isYou flags).
+        const url = new URL(getAgreementBaseUrl());
+        url.searchParams.set('scope', 'mine');
+        if (filters.engagementKind)
+            url.searchParams.set('engagementKind', filters.engagementKind);
+        if (filters.proposalStatus)
+            url.searchParams.set('proposalStatus', filters.proposalStatus);
+        if (filters.hasTask != null)
+            url.searchParams.set('hasTask', String(filters.hasTask));
+        const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get my agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['agreements']) ? data['agreements'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get my agreements failed: ${e.message}`);
+        return [];
+    }
+}
+export async function getAgreement(agreementId, creds) {
+    if (!agreementId)
+        return null;
+    assertCreds(creds, 'get agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return null;
+        }
+        const data = await res.json().catch(() => null);
+        return data?.['agreement'] ?? null;
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${e.message}`);
+        return null;
+    }
+}
+export async function createAgreement(body, creds) {
+    if (!body)
+        throw new Error('Body is required for agreement creation');
+    assertCreds(creds, 'agreement creation');
+    // Canonical REST create: POST /agreements.
+    const res = await fetch(getAgreementBaseUrl(), {
+        method: 'POST',
+        headers: buildHeaders(creds),
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const responseBody = await res.text().catch(() => '');
+        throwApiError(res, responseBody, `Agreement creation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements');
+    }
+    return data;
+}
+export async function revokeAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required for revocation');
+    assertCreds(creds, 'agreement revocation');
+    // ZIG-207: canonical REST verb. Legacy POST /agreements/:id/revoke stays
+    // serving the identical handler (with Deprecation headers) until PR-F.
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}`, {
+        method: 'DELETE',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Agreement revocation failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { ok, agreement } from DELETE /agreements/:id');
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// Chat links
+// ---------------------------------------------------------------------------
+export async function getAgreementsByChat(chatId, creds) {
+    if (!chatId)
+        return [];
+    assertCreds(creds, 'get agreements by chat');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/by-chat/${encodeURIComponent(chatId)}`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        const links = data?.['links'] ?? data?.['agreements'];
+        return Array.isArray(links) ? links : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${e.message}`);
+        return [];
+    }
+}
+export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
+    if (!agreementId || !chatId)
+        return null;
+    assertCreds(creds, 'link agreement to chat');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/link`, {
+            method: 'POST',
+            headers: buildHeaders(creds),
+            body: JSON.stringify({ chatId, linkType }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return null;
+        }
+        return await res.json().catch(() => null);
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${e.message}`);
+        return null;
+    }
+}
+export async function getChatsForAgreement(agreementId, creds) {
+    if (!agreementId)
+        return [];
+    assertCreds(creds, 'get chats for agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/chats`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['links']) ? data['links'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${e.message}`);
+        return [];
+    }
+}
+export async function joinAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required for join');
+    assertCreds(creds, 'join agreement');
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/join`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Join agreement failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['chatId']) {
+        throw new Error('Invalid response: expected { chatId } from /agreements/:id/join');
+    }
+    return data;
+}
+export async function linkArtifactToAgreement(agreementId, artifactId, linkType = 'produced', creds) {
+    if (!agreementId || !artifactId)
+        return null;
+    assertCreds(creds, 'link artifact to agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/artifacts`, {
+            method: 'POST',
+            headers: buildHeaders(creds),
+            body: JSON.stringify({ artifactId, linkType }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Link artifact failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return null;
+        }
+        return await res.json().catch(() => null);
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Link artifact failed: ${e.message}`);
+        return null;
+    }
+}
+export async function getArtifactsForAgreement(agreementId, creds) {
+    if (!agreementId)
+        return [];
+    assertCreds(creds, 'get artifacts for agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/artifacts`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get artifacts failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['artifacts']) ? data['artifacts'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get artifacts failed: ${e.message}`);
+        return [];
+    }
+}
+export async function linkUserToAgreement(agreementId, userId, role, creds) {
+    if (!agreementId || !userId || !role)
+        return null;
+    assertCreds(creds, 'link user to agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
+            method: 'POST',
+            headers: buildHeaders(creds),
+            body: JSON.stringify({ userId, role }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return null;
+        }
+        return await res.json().catch(() => null);
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${e.message}`);
+        return null;
+    }
+}
+export async function getUsersForAgreement(agreementId, creds) {
+    if (!agreementId)
+        return [];
+    assertCreds(creds, 'get users for agreement');
+    try {
+        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
+            method: 'GET',
+            headers: buildHeaders(creds),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+            return [];
+        }
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['users']) ? data['users'] : [];
+    }
+    catch (e) {
+        runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${e.message}`);
+        return [];
+    }
+}
+/**
+ * @deprecated Prefer {@link proposeDirectTo}, {@link proposeBroadcast},
+ * {@link delegateAgreement}, or {@link publishOpenQuest}.
+ */
+export async function createContract(input, creds) {
+    assertCreds(creds, 'contract creation');
+    const { kind, ...rest } = input;
+    if (kind === 'direct')
+        return proposeDirectTo(rest, creds);
+    if (kind === 'delegate')
+        return delegateAgreement(rest, creds);
+    return publishOpenQuest(rest, creds);
+}
+/** Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted"). */
+export async function publishOpenQuest(payload, creds) {
+    return publishToLedger(payload, creds);
+}

package/dist/http/ArtifactsClient.d.ts

@@ -0,0 +1,48 @@
+import 'dotenv/config';
+export type ArtifactVisibility = 'chat' | 'agent-private';
+export interface ListArtifactsOptions {
+    after?: string;
+    limit?: number;
+}
+export interface ListArtifactsQuery {
+    chatId?: string;
+    agreementId?: string;
+}
+export interface ListArtifactsResult {
+    artifacts: unknown[];
+    latestSequence: string | null;
+}
+export interface WriteArtifactInput {
+    text: string;
+    content_type?: string;
+    visibility?: ArtifactVisibility;
+    /** When the artifact is associated with a chat. */
+    chatId?: string;
+    /** When the artifact is associated with an agreement (and optionally a task). */
+    agreementId?: string;
+    taskId?: string;
+    service?: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare class ArtifactsClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    constructor(operatorKey: string, agentId: string);
+    list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
+    /**
+     * Record an agent thought as an `agent-private` artifact. Replaces the
+     * `ContextWriter.recordEvent({ kind: 'thought' })` hack.
+     *
+     * Note: the artifact write endpoint lives in the existing chat/agreement
+     * write paths; this helper is the SDK contract. Until the backend write
+     * endpoint is updated to accept `visibility`, this falls back to logging
+     * locally (operators can still wire their own sink).
+     */
+    recordThought(chatId: string, text: string): Promise<void>;
+    write(input: WriteArtifactInput): Promise<void>;
+    private _headers;
+}

package/dist/http/ArtifactsClient.js

@@ -0,0 +1,90 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/**
+ * 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.
+ */
+export class ArtifactsClient {
+    operatorKey;
+    agentId;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('ArtifactsClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('ArtifactsClient: agentId is required (operator-token impersonation)');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+    }
+    async list(q, opts = {}) {
+        if ((q.chatId && q.agreementId) || (!q.chatId && !q.agreementId)) {
+            throw new Error('ArtifactsClient.list: pass exactly one of chatId or agreementId');
+        }
+        const url = new URL(`${getBackendUrl()}/artifacts`);
+        if (q.chatId)
+            url.searchParams.set('chatId', q.chatId);
+        if (q.agreementId)
+            url.searchParams.set('agreementId', q.agreementId);
+        if (opts.after)
+            url.searchParams.set('after', opts.after);
+        if (opts.limit != null)
+            url.searchParams.set('limit', String(opts.limit));
+        const res = await fetch(url.toString(), { headers: this._headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throw new Error(`ArtifactsClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Record an agent thought as an `agent-private` artifact. Replaces the
+     * `ContextWriter.recordEvent({ kind: 'thought' })` hack.
+     *
+     * Note: the artifact write endpoint lives in the existing chat/agreement
+     * write paths; this helper is the SDK contract. Until the backend write
+     * endpoint is updated to accept `visibility`, this falls back to logging
+     * locally (operators can still wire their own sink).
+     */
+    async recordThought(chatId, text) {
+        return this.write({
+            chatId,
+            text,
+            content_type: 'thought',
+            visibility: 'agent-private',
+        });
+    }
+    async write(input) {
+        if (!input.text || !input.text.trim())
+            return;
+        if ((input.chatId && input.agreementId) || (!input.chatId && !input.agreementId)) {
+            throw new Error('ArtifactsClient.write: pass exactly one of chatId or agreementId');
+        }
+        const url = `${getBackendUrl()}/artifacts`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({
+                text: input.text.trim(),
+                content_type: input.content_type ?? 'text',
+                visibility: input.visibility ?? 'chat',
+                chatId: input.chatId,
+                agreementId: input.agreementId,
+                taskId: input.taskId,
+                service: input.service,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            // Soft-fail: artifact writes are breadcrumbs, not load-bearing.
+            runtimeLog.warn('ArtifactsClient', `⚠️ write failed ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+        }
+    }
+    _headers() {
+        return {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${this.operatorKey}`,
+            'X-Agent-Id': this.agentId,
+        };
+    }
+}

package/dist/http/ChatClient.d.ts

@@ -0,0 +1,34 @@
+import 'dotenv/config';
+import { type Creds } from '../types.js';
+export interface ChatSummary {
+    chatId: string;
+    userIds?: string[];
+    agentIds?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export declare function openConversation(participantId: string, creds: Creds): Promise<{
+    chatId: string;
+}>;
+export interface SendChatMessageInput {
+    chatId: string;
+    receiverId: string;
+    text: string;
+    messageId: string;
+    entryType?: string;
+    contentType?: string;
+    underAgreementId?: string;
+}
+export interface SendChatMessageResult {
+    success: boolean;
+    message: string;
+    messageId: string;
+    chatId: string;
+}
+/**
+ * POST /chats/:chatId/messages as an impersonated delegate agent.
+ * Requires operator token + X-Agent-Id (ZIG-222).
+ */
+export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
+export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;