@ziggs-ai/api-client 0.10.0 → 0.10.2

package/dist/capabilities/artifacts.js

@@ -17,6 +17,10 @@ function reportingHint(env, contentType, taskId) {
     }
     return `Reporting finished work? Record it with contentType=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
 }
+/** ZIG-1320 — inline body cap + escape hatch, shared by SDK/MCP descriptions. */
+const ARTIFACT_RECORD_INLINE_CAP = 'Inline text max 50000 characters. Over that: use ziggs_artifact_upload_url ' +
+    '(file rail), or record an index artifact plus part artifacts and list the ' +
+    'part ids in the index. The server does not auto-split.';
 export const recordArtifactCapability = {
     key: 'artifact_record',
     names: { sdk: 'artifact_record', mcp: 'ziggs_artifact_record' },
@@ -25,17 +29,23 @@ export const recordArtifactCapability = {
         sdk: 'Write an artifact. Scope is optional: pass agreementId or chatId to record it there, ' +
             'or pass no scope at all to record it as yours alone and attach it somewhere later. ' +
             'Set visibility explicitly. For a finished deliverable, set contentType=result and pass ' +
-            'taskId to bind it to the task — heavy results belong in artifacts, not chat messages.',
+            'taskId to bind it to the task — heavy results belong in artifacts, not chat messages. ' +
+            ARTIFACT_RECORD_INLINE_CAP,
         mcp: 'Write an artifact. Scope is optional — pass agreementId or chatId to record it into that ' +
             'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
             '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. ' +
-            'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only).',
+            'Finished work is the task result — set it with ziggs_task_set_result; never report finished work as a chat message (chat is conversation only). ' +
+            ARTIFACT_RECORD_INLINE_CAP,
     },
     annotation: 'write',
     params: {
-        text: { type: 'string', required: true, description: 'Artifact body' },
+        text: {
+            type: 'string',
+            required: true,
+            description: 'Artifact body (max 50000 chars). Over limit: ziggs_artifact_upload_url or index+parts.',
+        },
         visibility: {
             type: 'string',
             required: true,

package/dist/http/ArtifactsClient.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Inline `POST /artifacts` body cap (matches backend
+ * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
+ * server does not auto-split (ZIG-1320).
+ */
+export declare const ARTIFACT_INLINE_TEXT_MAX_CHARS = 50000;
+/** ZIG-1320 — named escape hatch for agents that hit the inline cap. */
+export declare const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT: string;
 export type ArtifactVisibility = 'chat' | 'agent-private';
 export interface ListArtifactsOptions {
     after?: string;

package/dist/http/ArtifactsClient.js

@@ -2,6 +2,17 @@ import { runtimeLog } from '../shared/runtimeLog.js';
 import { throwApiError } from '../shared/apiError.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * Inline `POST /artifacts` body cap (matches backend
+ * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
+ * server does not auto-split (ZIG-1320).
+ */
+export const ARTIFACT_INLINE_TEXT_MAX_CHARS = 50_000;
+/** ZIG-1320 — named escape hatch for agents that hit the inline cap. */
+export const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT = `text exceeds ${ARTIFACT_INLINE_TEXT_MAX_CHARS} characters. ` +
+    'For larger content use ziggs_artifact_upload_url (file rail), or split into ' +
+    'an index artifact plus part artifacts and list the part ids in the index. ' +
+    'The server does not auto-split.';
 function resolveUploadBytes(input) {
     if (input.content != null) {
         return Buffer.isBuffer(input.content)
@@ -122,12 +133,18 @@ export class ArtifactsClient {
             throw new Error('ArtifactsClient.writeStrict: text is required');
         }
         this._assertScopeXor(input);
+        const text = input.text.trim();
+        // ZIG-1320: refuse before the wire so MCP/SDK get a named escape hatch
+        // instead of a bare class-validator string.
+        if (text.length > ARTIFACT_INLINE_TEXT_MAX_CHARS) {
+            throw new Error(`ArtifactsClient.writeStrict: ${ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT}`);
+        }
         const url = `${getBackendUrl()}/artifacts`;
         const res = await fetch(url, {
             method: 'POST',
             headers: this._headers(),
             body: JSON.stringify({
-                text: input.text.trim(),
+                text,
                 contentType: input.contentType ?? 'text',
                 visibility: input.visibility ?? 'chat',
                 chatId: input.chatId,

package/dist/http/TaskClient.d.ts

@@ -1,4 +1,22 @@
 import { type Creds, type Task, type TaskState } from '../types.js';
+/**
+ * ZIG-1321 — thin confirmation from task write verbs. Full object stays on
+ * getTask / ziggs_task_get.
+ */
+export interface TaskWriteConfirm {
+    ok: true;
+    taskId: string;
+    state: TaskState;
+    updatedAt?: string;
+    status?: string;
+    stepCount?: number;
+    structureChanged?: boolean;
+    stepId?: string;
+    stepStatus?: string;
+    resultRecorded?: boolean;
+    terminalState?: string;
+    [key: string]: unknown;
+}
 /**
  * When the buyer reviews a task's plan. Task-rail only — an agreement has no
  * plan to review, which is why cut this from the propose/counter/
@@ -32,10 +50,10 @@ export interface UpdateTaskStateData {
      */
     idempotencyKey?: string;
 }
-export declare function updateTaskState(taskId: string, state: TaskState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<Task>;
+export declare function updateTaskState(taskId: string, state: TaskState, 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<Task>;
+export declare function cancelTask(taskId: string, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function getSubtasks(parentTaskId: string, creds: Creds): Promise<Task[]>;
 export interface PlanReplaceStep {
     /** Omit to let the server mint `step-<n>`. */
@@ -52,10 +70,10 @@ export interface PlanReplaceStep {
     /** Optional step output stored with this replace. */
     result?: unknown;
 }
-export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<Task>;
-export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<Task>;
-export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<Task>;
-export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<Task>;
+export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<TaskWriteConfirm>;
+export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<TaskWriteConfirm>;
+export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<TaskWriteConfirm>;
+export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<TaskWriteConfirm>;
 export interface ListTasksOptions {
     state?: string;
     cursor?: string;
@@ -85,15 +103,15 @@ export declare class TaskClient {
     constructor(operatorKey: string, agentId?: string);
     createTask(data: CreateTaskData): Promise<Task>;
     getTask(taskId: string): Promise<Task>;
-    updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<Task>;
+    updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<TaskWriteConfirm>;
     getActiveTasksForAgent(agentId: string): Promise<Task[]>;
     getActiveTasksForChat(chatId: string): Promise<Task[]>;
-    cancelTask(taskId: string): Promise<Task>;
+    cancelTask(taskId: string): Promise<TaskWriteConfirm>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
-    replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<Task>;
-    updateTaskPlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
-    reportTask(taskId: string, message?: string): Promise<Task>;
-    setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task>;
+    replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<TaskWriteConfirm>;
+    updateTaskPlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<TaskWriteConfirm>;
+    reportTask(taskId: string, message?: string): Promise<TaskWriteConfirm>;
+    setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<TaskWriteConfirm>;
     listTasks(options?: ListTasksOptions): Promise<ListTasksResult>;
     countTasks(filters?: CountTasksFilters): Promise<number>;
 }

package/dist/http/TaskClient.js

@@ -24,10 +24,54 @@ function extractTask(data) {
     if (d['task'] && typeof d['task'] === 'object' && d['task']['taskId']) {
         return d['task'];
     }
-    if (d['taskId'])
+    // Top-level task document (GET / create). Do not treat ZIG-1321 thin write
+    // confirms (`ok: true`, no description) as a Task.
+    if (typeof d['taskId'] === 'string' && d['ok'] !== true) {
         return d;
+    }
     return null;
 }
+function extractWriteConfirm(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const d = data;
+    // New thin shape (no nested task / no description dump).
+    if (typeof d['taskId'] === 'string' &&
+        typeof d['state'] === 'string' &&
+        d['task'] === undefined &&
+        d['description'] === undefined) {
+        return {
+            ok: true,
+            taskId: d['taskId'],
+            state: d['state'],
+            ...(typeof d['updatedAt'] === 'string' || d['updatedAt'] instanceof Date
+                ? { updatedAt: String(d['updatedAt']) }
+                : {}),
+            ...(typeof d['status'] === 'string' ? { status: d['status'] } : {}),
+            ...(typeof d['stepCount'] === 'number' ? { stepCount: d['stepCount'] } : {}),
+            ...(typeof d['structureChanged'] === 'boolean'
+                ? { structureChanged: d['structureChanged'] }
+                : {}),
+            ...(typeof d['stepId'] === 'string' ? { stepId: d['stepId'] } : {}),
+            ...(typeof d['stepStatus'] === 'string' ? { stepStatus: d['stepStatus'] } : {}),
+            ...(d['resultRecorded'] === true ? { resultRecorded: true } : {}),
+            ...(typeof d['terminalState'] === 'string'
+                ? { terminalState: d['terminalState'] }
+                : {}),
+        };
+    }
+    // Legacy fat echo — compress to the thin fields so callers stay forward-compat.
+    const task = extractTask(data);
+    if (!task?.taskId || !task.state)
+        return null;
+    return {
+        ok: true,
+        taskId: task.taskId,
+        state: task.state,
+        ...(task.updatedAt ? { updatedAt: task.updatedAt } : {}),
+        ...(typeof d['status'] === 'string' ? { status: d['status'] } : {}),
+    };
+}
 export async function createTask(taskData, creds) {
     if (!taskData)
         throw new Error('Task data is required for task creation');
@@ -85,10 +129,10 @@ export async function updateTaskState(taskId, state, data = {}, creds) {
         throwApiError(res, body, `Task state update failed: ${res.status} ${res.statusText}`);
     }
     const result = await res.json().catch(() => null);
-    const task = extractTask(result);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(result);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 export async function getActiveTasksForAgent(agentId, creds) {
     if (!agentId)
@@ -182,10 +226,10 @@ export async function cancelTask(taskId, creds) {
         throwApiError(res, body, `Task cancel failed: ${res.status} ${res.statusText}`);
     }
     const result = await res.json().catch(() => null);
-    const task = extractTask(result);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(result);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 export async function getSubtasks(parentTaskId, creds) {
     if (!parentTaskId)
@@ -219,10 +263,10 @@ export async function replaceTaskPlan(taskId, steps, creds) {
         throwApiError(res, responseBody, `Plan replace failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    const task = extractTask(data);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 export async function updateTaskPlanStep(taskId, stepId, status, result, creds) {
     if (!taskId)
@@ -242,10 +286,10 @@ export async function updateTaskPlanStep(taskId, stepId, status, result, creds)
         throwApiError(res, responseBody, `Plan step update failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    const task = extractTask(data);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 // ---------------------------------------------------------------------------
 // Reporting & satisfaction
@@ -264,10 +308,10 @@ export async function reportTask(taskId, message = '', creds) {
         throwApiError(res, body, `Task report failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    const task = extractTask(data);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 export async function setTaskSatisfaction(taskId, satisfaction, creds) {
     if (!taskId)
@@ -285,10 +329,10 @@ export async function setTaskSatisfaction(taskId, satisfaction, creds) {
         throwApiError(res, body, `Task satisfaction failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    const task = extractTask(data);
-    if (!task)
-        throw new Error('Invalid response: task data not found');
-    return task;
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
 }
 export async function listTasks(options = {}, creds) {
     assertCreds(creds, 'list tasks');

package/dist/http/index.d.ts

@@ -5,7 +5,7 @@ export * from './agreementFlows.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
-export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
+export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ViaKind, } from './ContextReadClient.js';

package/dist/http/index.js

@@ -6,7 +6,7 @@ export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient, 
 // agreement lanes are not chats — callers scope artifact writes with this.
-artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
+artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",