@ziggs-ai/api-client 0.9.3 → 0.9.5

package/dist/capabilities/artifacts.d.ts

@@ -28,4 +28,12 @@ export declare const shareArtifactCapability: CapabilityDefinition;
  * deliverable to a task; use artifact_share to hand it to ONE agent instead.
  */
 export declare const attachArtifactCapability: CapabilityDefinition;
+/**
+ * File deliverables (presign → PUT → complete). Text `artifact_record` stays
+ * for text bodies; use this rail when the payload is a file on object storage.
+ */
+export declare const uploadArtifactUrlCapability: CapabilityDefinition;
+export declare const completeArtifactFileCapability: CapabilityDefinition;
+export declare const downloadArtifactCapability: CapabilityDefinition;
+export declare const reextractArtifactCapability: CapabilityDefinition;
 export declare const ARTIFACT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/artifacts.js

@@ -269,9 +269,199 @@ export const attachArtifactCapability = {
         };
     },
 };
+/**
+ * File deliverables (presign → PUT → complete). Text `artifact_record` stays
+ * for text bodies; use this rail when the payload is a file on object storage.
+ */
+export const uploadArtifactUrlCapability = {
+    key: 'artifact_upload_url',
+    names: { sdk: 'artifact_upload_url', mcp: 'ziggs_artifact_upload_url' },
+    descriptions: {
+        sdk: 'Start a file artifact upload. Returns a short-lived uploadUrl. PUT the exact ' +
+            'byteSize bytes to that URL (Content-Type = mime), then call artifact_complete_file ' +
+            'with the sha256 hex of those bytes. Pass contentBase64 (or have the runtime supply ' +
+            'content) to have this tool PUT for you and return checksum. When extractionStatus ' +
+            'becomes ok, read extracted text via context_read / the extracted-text child — not ' +
+            'by stuffing file bytes into artifact_record.',
+        mcp: 'Start a file artifact upload (pdf/docx/hwpx/md/txt). Returns uploadUrl + artifactId. ' +
+            'PUT the file bytes to uploadUrl with the declared mime, then call ' +
+            'ziggs_artifact_complete_file with sha256 hex. Prefer contentBase64 so this tool PUTs ' +
+            'and returns checksum for you. Scope optional (chatId / agreementId / taskId) like ' +
+            'ziggs_artifact_record. Do not put large file bodies into ziggs_artifact_record. ' +
+            'After extract finishes (extractionStatus=ok), read text from context / the derived ' +
+            'extracted-text artifact.',
+    },
+    annotation: 'write',
+    params: {
+        filename: { type: 'string', required: true, description: 'Original filename' },
+        mime: {
+            type: 'string',
+            required: true,
+            description: 'Content-Type for the S3 PUT (e.g. text/plain; charset=utf-8)',
+        },
+        byteSize: {
+            type: 'number',
+            required: true,
+            description: 'Exact byte length of the object that will be PUT (UTF-8 length for text)',
+        },
+        format: {
+            type: 'string',
+            enum: ['pdf', 'docx', 'hwpx', 'md', 'txt'],
+            description: 'Optional; inferred from filename when omitted',
+        },
+        visibility: {
+            type: 'string',
+            enum: ['chat', 'agent-private'],
+            description: 'Defaults server-side when omitted',
+        },
+        chatId: { type: 'string', description: 'Optional chat scope' },
+        agreementId: {
+            type: 'string',
+            description: 'Optional agreement scope; mutually exclusive with chatId',
+        },
+        taskId: { type: 'string', description: 'Optional task binding' },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Optional dedup key for the upload-url create',
+        },
+        contentBase64: {
+            type: 'string',
+            description: 'Optional base64 file bytes. When set, this tool PUTs to uploadUrl and returns checksum for ziggs_artifact_complete_file.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const filename = args['filename'];
+        const mime = args['mime'];
+        const byteSize = args['byteSize'];
+        if (!filename?.trim())
+            throw new Error('filename is required');
+        if (!mime?.trim())
+            throw new Error('mime is required');
+        if (!Number.isFinite(byteSize) || byteSize < 1) {
+            throw new Error('byteSize must be a positive number');
+        }
+        const visibility = args['visibility'];
+        if (visibility != null &&
+            visibility !== 'chat' &&
+            visibility !== 'agent-private') {
+            throw new Error('visibility must be chat or agent-private');
+        }
+        const creds = fullCreds(env);
+        const result = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).uploadUrl({
+            filename,
+            mime,
+            byteSize: Math.trunc(byteSize),
+            format: args['format'],
+            visibility,
+            chatId: args['chatId'],
+            agreementId: args['agreementId'],
+            taskId: args['taskId'],
+            idempotencyKey: args['idempotencyKey'],
+            contentBase64: args['contentBase64'],
+        });
+        return {
+            ok: true,
+            ...result,
+            next: result.checksum
+                ? 'Call artifact_complete_file / ziggs_artifact_complete_file with this artifactId and checksum.'
+                : 'PUT the exact byteSize bytes to uploadUrl (Content-Type=mime), then call artifact_complete_file / ziggs_artifact_complete_file with sha256 hex of those bytes.',
+        };
+    },
+};
+export const completeArtifactFileCapability = {
+    key: 'artifact_complete_file',
+    names: { sdk: 'artifact_complete_file', mcp: 'ziggs_artifact_complete_file' },
+    descriptions: {
+        sdk: 'Finish a file upload after the S3 PUT. Pass artifactId + sha256 hex of the bytes ' +
+            'you uploaded. Sets extractionStatus=pending and enqueues extract. Poll artifact_list ' +
+            'or context until extractionStatus is ok/failed; download still works while pending.',
+        mcp: 'Finish a file upload after the S3 PUT (or after ziggs_artifact_upload_url returned ' +
+            'checksum). Pass artifactId + sha256 hex. Enqueues text extract. When extractionStatus ' +
+            'is ok, read extracted text via ziggs_context_read / grants — file bytes stay on ' +
+            'ziggs_artifact_download.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'From upload-url' },
+        checksum: {
+            type: 'string',
+            required: true,
+            description: 'sha256 hex of the bytes that were PUT',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        const checksum = args['checksum'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        if (!checksum)
+            throw new Error('checksum is required');
+        const creds = fullCreds(env);
+        const artifact = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).completeFile(artifactId, checksum);
+        return {
+            ok: true,
+            artifact,
+            note: 'Extract runs asynchronously. When extractionStatus is ok, read the derived text; use artifact_download for original bytes.',
+        };
+    },
+};
+export const downloadArtifactCapability = {
+    key: 'artifact_download',
+    names: { sdk: 'artifact_download', mcp: 'ziggs_artifact_download' },
+    descriptions: {
+        sdk: 'Get a short-lived (60s) presigned download URL for a file artifact you can read. ' +
+            'Returns downloadUrl, expiresAt, filename — fetch the URL yourself; do not expect ' +
+            'inline file bytes in this response.',
+        mcp: 'Presigned download for a file artifact you can read. Returns { downloadUrl, expiresAt, ' +
+            'filename } (TTL ~60s). GET the URL for bytes. For extracted plain text after extract ' +
+            'ok, prefer ziggs_context_read / the extracted-text child over downloading the binary.',
+    },
+    annotation: 'read-only',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'File artifact id' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const creds = fullCreds(env);
+        const out = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).download(artifactId);
+        return { ok: true, ...out };
+    },
+};
+export const reextractArtifactCapability = {
+    key: 'artifact_reextract',
+    names: { sdk: 'artifact_reextract', mcp: 'ziggs_artifact_reextract' },
+    descriptions: {
+        sdk: 'Re-queue text extraction for a file artifact you authored when status is ok or failed ' +
+            '(pending → conflict). On success a new extracted-text row supersedes the previous one.',
+        mcp: 'Re-queue extract for a file you authored (extractionStatus ok or failed only). ' +
+            'Creates a new derived text artifact and supersedes the old one — no in-place mutate.',
+    },
+    annotation: 'write',
+    params: {
+        artifactId: { type: 'string', required: true, description: 'File artifact id' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const artifactId = args['artifactId'];
+        if (!artifactId)
+            throw new Error('artifactId is required');
+        const creds = fullCreds(env);
+        const artifact = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).reExtract(artifactId);
+        return { ok: true, artifact };
+    },
+};
 export const ARTIFACT_CAPABILITIES = [
     recordArtifactCapability,
     listArtifactsCapability,
     shareArtifactCapability,
     attachArtifactCapability,
+    uploadArtifactUrlCapability,
+    completeArtifactFileCapability,
+    downloadArtifactCapability,
+    reextractArtifactCapability,
 ];

package/dist/capabilities/chat.js

@@ -35,13 +35,23 @@ export const openConversationCapability = {
     handler: async (args, env) => {
         if (!args['participantId'])
             throw new Error('participantId is required');
-        const { chatId } = await openConversation(args['participantId'], fullCreds(env), {
-            newChat: args['newChat'] === true,
-        });
+        const { chatId, reused } = await openConversation(args['participantId'], fullCreds(env), { newChat: args['newChat'] === true });
         const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
+        const grantNote = `Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`;
+        // ZIG-1216: word the note from the outcome instead of covering both cases.
+        // "Open (or reused)" told the agent the distinction existed and then
+        // withheld it — worse than silence, because the agent cannot even tell
+        // there is something to look up. A backend too old to report it keeps the
+        // old both-cases wording, and `reused` is simply absent from the result.
+        const outcomeNote = reused === true
+            ? 'Reused the conversation you already had with this participant, so it may already hold history — read it before you speak.'
+            : reused === false
+                ? 'Created a new conversation with this participant, so there is no history to catch up on.'
+                : 'Conversation is open (or reused).';
         return {
             chatId,
-            note: `Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in ${lister} scopeKind=chat for context reads.`,
+            ...(typeof reused === 'boolean' ? { reused } : {}),
+            note: `${outcomeNote} ${grantNote}`,
         };
     },
 };

package/dist/capabilities/index.d.ts

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -7,5 +7,5 @@ export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
 export { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
-export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, } from './artifacts.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/http/ArtifactsClient.d.ts

@@ -37,6 +37,43 @@ export interface WriteArtifactInput {
      */
     idempotencyKey?: string;
 }
+export type ArtifactFileFormat = 'pdf' | 'docx' | 'hwpx' | 'md' | 'txt';
+export interface ArtifactUploadUrlInput {
+    filename: string;
+    mime: string;
+    /** Exact UTF-8 / file byte length of the object that will be PUT. */
+    byteSize: number;
+    format?: ArtifactFileFormat;
+    visibility?: ArtifactVisibility;
+    chatId?: string;
+    agreementId?: string;
+    taskId?: string;
+    service?: Record<string, unknown>;
+    idempotencyKey?: string;
+    /**
+     * Optional raw bytes. When set, the client PUTs to the presigned URL and
+     * returns `checksum` for {@link ArtifactsClient.completeFile}.
+     */
+    content?: Uint8Array | Buffer;
+    /** Optional base64 of the same bytes as `content`. */
+    contentBase64?: string;
+}
+export interface ArtifactUploadUrlResult {
+    artifactId: string;
+    uploadUrl: string;
+    expiresAt: string;
+    storageKey: string;
+    /** Set when this client performed the S3 PUT. */
+    putOk?: boolean;
+    /** sha256 hex when content was supplied and PUT succeeded. */
+    checksum?: string;
+}
+export type ArtifactFileView = Record<string, unknown> & {
+    artifactId?: string;
+    extractionStatus?: string | null;
+    extractionError?: string | null;
+    filename?: string | null;
+};
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
@@ -110,6 +147,19 @@ export declare class ArtifactsClient {
     attachToTask(artifactId: string, taskId: string, role?: 'input' | 'output'): Promise<{
         success: boolean;
     }>;
+    /**
+     * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
+     * then {@link completeFile}. Optional `content` / `contentBase64` performs the
+     * S3 PUT here and returns a sha256 so complete can follow immediately.
+     */
+    uploadUrl(input: ArtifactUploadUrlInput): Promise<ArtifactUploadUrlResult>;
+    completeFile(artifactId: string, checksum: string): Promise<ArtifactFileView>;
+    download(artifactId: string): Promise<{
+        downloadUrl: string;
+        expiresAt: string;
+        filename: string;
+    }>;
+    reExtract(artifactId: string): Promise<ArtifactFileView>;
     private _attach;
     /**
      * ZIG-1037 — at most one container, and none is fine.

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';
+function resolveUploadBytes(input) {
+    if (input.content != null) {
+        return Buffer.isBuffer(input.content)
+            ? input.content
+            : Buffer.from(input.content);
+    }
+    if (input.contentBase64 != null && input.contentBase64 !== '') {
+        return Buffer.from(input.contentBase64, 'base64');
+    }
+    return null;
+}
 /**
  * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
  * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
@@ -159,6 +170,128 @@ export class ArtifactsClient {
             role,
         });
     }
+    /**
+     * File artifact rail — presign PUT, then client uploads bytes to `uploadUrl`,
+     * then {@link completeFile}. Optional `content` / `contentBase64` performs the
+     * S3 PUT here and returns a sha256 so complete can follow immediately.
+     */
+    async uploadUrl(input) {
+        if (!input.filename?.trim()) {
+            throw new Error('ArtifactsClient.uploadUrl: filename is required');
+        }
+        if (!input.mime?.trim()) {
+            throw new Error('ArtifactsClient.uploadUrl: mime is required');
+        }
+        if (!Number.isInteger(input.byteSize) || input.byteSize < 1) {
+            throw new Error('ArtifactsClient.uploadUrl: byteSize must be a positive integer');
+        }
+        this._assertScopeXor({
+            text: '.',
+            chatId: input.chatId,
+            agreementId: input.agreementId,
+        });
+        const bytes = resolveUploadBytes(input);
+        if (bytes && bytes.byteLength !== input.byteSize) {
+            throw new Error(`ArtifactsClient.uploadUrl: byteSize ${input.byteSize} does not match content length ${bytes.byteLength}`);
+        }
+        const url = `${getBackendUrl()}/artifacts/upload-url`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({
+                filename: input.filename.trim(),
+                mime: input.mime.trim(),
+                byteSize: input.byteSize,
+                format: input.format,
+                visibility: input.visibility,
+                chatId: input.chatId,
+                agreementId: input.agreementId,
+                taskId: input.taskId,
+                service: input.service,
+                ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+            }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `artifact upload-url failed: ${res.status} ${res.statusText}`);
+        }
+        const parsed = text
+            ? JSON.parse(text)
+            : {};
+        if (!parsed.artifactId || !parsed.uploadUrl) {
+            throw new Error('artifact upload-url response missing artifactId/uploadUrl');
+        }
+        if (bytes) {
+            const put = await fetch(parsed.uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': input.mime.trim() },
+                // Blob/Uint8Array — Buffer is not always a DOM BodyInit under tsc DOM libs.
+                body: new Uint8Array(bytes),
+            });
+            if (!put.ok) {
+                const putBody = await put.text().catch(() => '');
+                throw new Error(`S3 PUT failed: ${put.status} ${put.statusText}${putBody ? ` — ${putBody.slice(0, 200)}` : ''}`);
+            }
+            const { createHash } = await import('node:crypto');
+            parsed.checksum = createHash('sha256').update(bytes).digest('hex');
+            parsed.putOk = true;
+        }
+        return parsed;
+    }
+    async completeFile(artifactId, checksum) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.completeFile: artifactId is required');
+        if (!/^[a-f0-9]{64}$/i.test(checksum)) {
+            throw new Error('ArtifactsClient.completeFile: checksum must be sha256 hex');
+        }
+        const url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/complete`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({ checksum: checksum.toLowerCase() }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `artifact complete failed: ${res.status} ${res.statusText}`);
+        }
+        return text ? JSON.parse(text) : {};
+    }
+    async download(artifactId) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.download: artifactId is required');
+        const url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/download`;
+        const res = await fetch(url, { headers: this._headers() });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `artifact download failed: ${res.status} ${res.statusText}`);
+        }
+        const parsed = text
+            ? JSON.parse(text)
+            : {};
+        if (!parsed.downloadUrl || !parsed.expiresAt || !parsed.filename) {
+            throw new Error('artifact download response incomplete');
+        }
+        return {
+            downloadUrl: parsed.downloadUrl,
+            expiresAt: parsed.expiresAt,
+            filename: parsed.filename,
+        };
+    }
+    async reExtract(artifactId) {
+        if (!artifactId)
+            throw new Error('ArtifactsClient.reExtract: artifactId is required');
+        const url = `${getBackendUrl()}/artifacts/${encodeURIComponent(artifactId)}/re-extract`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this._headers(),
+            body: JSON.stringify({}),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `artifact re-extract failed: ${res.status} ${res.statusText}`);
+        }
+        return text ? JSON.parse(text) : {};
+    }
     async _attach(path, body) {
         const res = await fetch(`${getBackendUrl()}${path}`, {
             method: 'POST',

package/dist/http/ChatClient.d.ts

@@ -13,6 +13,7 @@ export declare function openConversation(participantId: string, creds: Creds, {
     newChat?: boolean;
 }): Promise<{
     chatId: string;
+    reused?: boolean;
 }>;
 export interface SendChatMessageInput {
     chatId: string;
@@ -80,6 +81,7 @@ export declare class ChatClient {
         newChat?: boolean;
     }): Promise<{
         chatId: string;
+        reused?: boolean;
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;

package/dist/http/ChatClient.js

@@ -36,7 +36,15 @@ export async function openConversation(participantId, creds, { newChat = false }
     if (!data?.['chatId'] || typeof data['chatId'] !== 'string') {
         throw new Error('Invalid response: expected { chatId } from POST /chats');
     }
-    return { chatId: data['chatId'] };
+    // ZIG-1216: left UNDEFINED rather than defaulted when the backend does not
+    // send it. A backend from before this field cannot be assumed to have created
+    // the room — defaulting to false would report a reused conversation as fresh,
+    // which is worse than saying nothing.
+    const reused = data['reused'];
+    return {
+        chatId: data['chatId'],
+        ...(typeof reused === 'boolean' ? { reused } : {}),
+    };
 }
 /**
  * POST /chats/:chatId/members — add user/agent; agent-invite may return pending admission (ZIG-426).

package/package.json

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