@ziggs-ai/api-client 0.32.0 → 0.33.0

package/dist/capabilities/context.js

@@ -293,6 +293,10 @@ function openBodyFromArgs(args) {
     return body;
 }
 function presentOpenResult(result, env) {
+    // Resource-routed OAuth calls let the backend select the assistant. Their
+    // local credentials have no agent id, so only the response can name it.
+    const actingAgentId = result.actingAgentId !== undefined
+        ? result.actingAgentId : fullCreds(env).agentId || undefined;
     // Expose a request-only next action, never execute it as part of a read.
     const requestTool = env.surface === 'mcp' ? 'ziggs_access_request' : 'access_request';
     const chatTool = env.surface === 'mcp' ? 'ziggs_chat_open' : 'chat_open';
@@ -302,7 +306,7 @@ function presentOpenResult(result, env) {
             return [];
         const row = item;
         const ask = row.grantRequest;
-        if (row.status !== 'active' || !isContextAccessRequest(ask) || ask.holderId !== fullCreds(env).agentId || !ask.scope?.id || !['artifact', 'chat', 'agreement', 'task'].includes(ask.scope.kind ?? ''))
+        if (row.status !== 'active' || !isContextAccessRequest(ask) || !actingAgentId || ask.holderId !== actingAgentId || !ask.scope?.id || !['artifact', 'chat', 'agreement', 'task'].includes(ask.scope.kind ?? ''))
             return [];
         return [{ kind: 'resume', tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { [`${ask.scope.kind}Id`]: ask.scope.id }, effect: 'read_only', note: 'Approval recorded. Open the original scope; the server rechecks expiry and revocation.' }];
     });
@@ -316,7 +320,7 @@ function presentOpenResult(result, env) {
                 : result.ref.kind === 'artifact' && result.outcome === 'unreadable'
                     ? [requestAccessAction({ scopeKind: 'artifact', scopeId: result.ref.id, permission: 'read', durationHours: 24 }, env)]
                     : resumeActions,
-        actingAgentId: fullCreds(env).agentId,
+        ...(actingAgentId !== undefined ? { actingAgentId } : {}),
         ...(!result.actions && result.ref.kind === 'artifact' && result.outcome !== 'ok' ? {
             requestAccessHint: `If a source you already read supplied this artifact reference and its human owner, ${requestTool} scopeKind=artifact can ask that owner for temporary read access without a prior grant. It needs a conversation with the owner; ${chatTool} can open or reuse one, subject to authorization. Discover the request tool's schema before calling it. This response does not confirm existence or ownership. A request grants no access until the human owner approves.`,
         } : {}),
@@ -409,15 +413,15 @@ export const accessRequestCapability = {
     title: 'Request access for yourself',
     annotation: 'write', needsAgentId: true,
     descriptions: {
-        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
-        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Name who to ask in recipientId; a pick the server cannot use here is refused, and the refusal lists who you can ask. Artifact requests also require chatId. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
+        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Name who to ask in recipientId; a pick the server cannot use here is refused, and the refusal lists who you can ask. Artifact requests also require chatId. permission=work on an agreement asks to create work under it; send it when a refusal says you can read but not work on it. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
     },
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
         scopeId: { type: 'string', description: 'Original resource id. Omit when using a hire agreementId to request its workspace summary.' },
         agreementId: { type: 'string', description: 'Artifact scope only: current hire id, used instead of scopeId to request the system-maintained workspace summary.' },
         reason: { type: 'string', required: true, description: 'Why access is needed and who will receive the reply or summary' },
-        permission: { type: 'string', enum: ['read', 'reply'], description: 'read by default; reply is read and reply and is only valid for a chat' },
+        permission: { type: 'string', enum: ['read', 'reply', 'work'], description: 'read by default; reply is read and reply and is only valid for a chat; work lets you create work under an agreement you can read but not work on, and lasts until it ends' },
         temporal: { type: 'string', enum: ['from-now', 'from-start'], description: 'Chat history requested; default from-now. Earlier messages need from-start. Other resources use from-start.' },
         durationHours: { type: 'number', description: 'Integer 1–168 hours after approval; default 24' },
         chatId: { type: 'string', description: 'Artifact or workspace requests only: existing conversation with the owner' },
@@ -437,8 +441,10 @@ export const accessRequestCapability = {
         if (Boolean(agreementId) === Boolean(scopeId) || (agreementId && scopeKind !== 'artifact'))
             throw new Error('Provide scopeId, or agreementId for its workspace summary artifact');
         const permission = args.permission ?? 'read';
-        if (!['read', 'reply'].includes(String(permission)) || (permission === 'reply' && scopeKind !== 'chat'))
+        if (!['read', 'reply', 'work'].includes(String(permission)) || (permission === 'reply' && scopeKind !== 'chat'))
             throw new Error('Only chat access may request reply permission');
+        if (permission === 'work' && scopeKind !== 'agreement')
+            throw new Error('Only agreement access may request work permission');
         if (args.temporal !== undefined && (!['from-now', 'from-start'].includes(String(args.temporal)) || (scopeKind !== 'chat' && args.temporal === 'from-now')))
             throw new Error('Only chats support from-now access');
         const durationHours = args.durationHours ?? 24;
@@ -451,8 +457,10 @@ export const accessRequestCapability = {
             durationHours, chatId: args.chatId,
             recipientId: typeof args.recipientId === 'string' ? args.recipientId.trim() : undefined,
         }, { idempotencyKey: args.idempotencyKey, laneId: creds.laneId });
+        const actingAgentId = result.actingAgentId ?? (creds.agentId || undefined);
         return {
-            ...result, outcome: 'pending', state: 'requested', actingAgentId: creds.agentId,
+            ...result, outcome: 'pending', state: 'requested',
+            ...(actingAgentId ? { actingAgentId } : {}),
             scope: result.scope ?? { kind: scopeKind, id: scopeId },
             appUrl: `${(env.webUrl ?? 'https://ziggsai.com').replace(/\/$/, '')}/app/agreements/${encodeURIComponent(result.agreementId)}`,
             resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } },

package/dist/http/ArtifactsClient.d.ts

@@ -90,14 +90,10 @@ export interface WriteArtifactInput {
      * When the deliverable lives outside Ziggs: both provider and http(s) URL.
      * The `text` is the in-Ziggs summary. Ziggs does not fetch the URL.
      */
-    externalRef?: {
-        provider: string;
-        url: string;
-    };
+    externalRef?: ArtifactExternalRef;
 }
-/** Every file format the server stores, in its order. One list for the type and the tool enums. */
-export declare const ARTIFACT_FILE_FORMATS: readonly ["pdf", "docx", "hwpx", "pptx", "md", "txt", "html", "mp3"];
-export type ArtifactFileFormat = (typeof ARTIFACT_FILE_FORMATS)[number];
+/** Every file format the server stores — the contracts list, re-exported under the names callers already use. */
+export { ARTIFACT_FILE_FORMATS, type ArtifactExternalRef, type ArtifactFileFormat } from '@ziggs-ai/contracts';
 export interface ArtifactUploadUrlInput {
     /** Short list name. Defaults to filename on the server when omitted. */
     name?: string;
@@ -137,6 +133,7 @@ export type ArtifactFileView = Record<string, unknown> & {
     extractionError?: string | null;
     filename?: string | null;
 };
+import type { ArtifactExternalRef, ArtifactFileFormat } from '@ziggs-ai/contracts';
 export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
 export declare function artifactScopeForSession(sessionId: string): {
     chatId: string;

package/dist/http/ArtifactsClient.js

@@ -13,8 +13,8 @@ export const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT = `text exceeds ${ARTIFACT_INL
     '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.';
-/** Every file format the server stores, in its order. One list for the type and the tool enums. */
-export const ARTIFACT_FILE_FORMATS = ['pdf', 'docx', 'hwpx', 'pptx', 'md', 'txt', 'html', 'mp3'];
+/** Every file format the server stores — the contracts list, re-exported under the names callers already use. */
+export { ARTIFACT_FILE_FORMATS } from '@ziggs-ai/contracts';
 function resolveUploadBytes(input) {
     if (input.content != null) {
         return Buffer.isBuffer(input.content)

package/dist/http/ContextGrantsClient.d.ts

@@ -102,7 +102,7 @@ export declare class ContextGrantsClient {
         scopeId?: string;
         agreementId?: string;
         reason: string;
-        permission?: 'read' | 'reply';
+        permission?: 'read' | 'reply' | 'work';
         temporal?: 'from-now' | 'from-start';
         durationHours?: number;
         chatId?: string;
@@ -116,6 +116,7 @@ export declare class ContextGrantsClient {
         status: 'pending_approval';
         agreementId: string;
         accessGranted: false;
+        actingAgentId?: string;
         scope?: {
             kind: string;
             id: string;

package/dist/http/ContextGrantsClient.js

@@ -80,7 +80,7 @@ export class ContextGrantsClient {
         if (result.status !== 'pending_approval' || !result.agreementId || result.accessGranted !== false) {
             throw new Error('Expected a pending access request with accessGranted=false');
         }
-        return { status: 'pending_approval', agreementId: result.agreementId, accessGranted: false, ...(result.scope ? { scope: result.scope } : {}), ...sentToOf(result) };
+        return { status: 'pending_approval', agreementId: result.agreementId, accessGranted: false, ...(typeof result.actingAgentId === 'string' && result.actingAgentId ? { actingAgentId: result.actingAgentId } : {}), ...(result.scope ? { scope: result.scope } : {}), ...sentToOf(result) };
     }
     async requestArtifactAccess(artifactId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/access-requests`, {

package/dist/http/ContextOpenClient.d.ts

@@ -51,6 +51,8 @@ export interface ContextOpenAccess {
     };
 }
 export interface ContextOpenResult {
+    /** Server-resolved caller; absent on older servers, null for human callers. */
+    actingAgentId?: string | null;
     /** Optional for servers predating resource action projections. */
     actions?: ResourceAction[];
     outcome: ContextOpenOutcome;

package/dist/http/InboxClient.d.ts

@@ -20,7 +20,9 @@ export declare class InboxClient {
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, instanceId?: string);
     private headers;
     private inboxUrl;
-    getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;
+    getInbox(opts?: InboxReadOptions & {
+        signal?: AbortSignal;
+    }): Promise<InboxEnvelope>;
     /**
      * Wait for assigned mail without taking the host lease.
      * Still sends X-Ziggs-Instance; the server ignores it on this route.

package/dist/http/InboxClient.js

@@ -50,6 +50,7 @@ export class InboxClient {
     async getInbox(opts = {}) {
         const res = await fetch(this.inboxUrl('/inbox', opts), {
             headers: this.headers(),
+            ...(opts.signal ? { signal: opts.signal } : {}),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {

package/dist/http/grants.d.ts

@@ -22,7 +22,7 @@ export type GrantHolderKind = 'user' | 'org' | 'agent';
  * both: `read` sees the scope, `write` takes part in it, `admit` brings others
  * in as well.
  */
-export type GrantAccessKind = 'read' | 'write' | 'admit';
+export type { GrantAccessKind };
 /**
  * The kind of principal-authored consent object a grant rests on. Every grant
  * is minted by one of these, or delegated from a parent grant that was.
@@ -62,6 +62,7 @@ export type { GrantScopeView, GrantCaveatView };
  * client believed a different subset of the row.
  */
 import type { GrantView, GrantScopeView, GrantCaveatView } from '@ziggs-ai/contracts';
+import type { GrantAccessKind } from '@ziggs-ai/contracts';
 export type { GrantView };
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export declare function grantCaveat(grant: GrantView, type: string): unknown | undefined;

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export type { DecisionOutcome, DecisionWords, DecisionWordsInput, } from './deci
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from './inboxAck.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
+/** The one way to show points (hundredths → ϟ5.00), shared with the web and the phone. */
+export { POINTS_GLYPH, formatPoints, formatPointsPrice } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
 export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdentity, hostIdentity, instanceIdentity, mcpConnectionIdentity, } from './instanceIdentity.js';
 export * from './utils/appUrls.js';

package/dist/index.js

@@ -18,6 +18,8 @@ export { ApiError } from './types.js';
 export { decisionWords, speakableActor } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
+/** The one way to show points (hundredths → ϟ5.00), shared with the web and the phone. */
+export { POINTS_GLYPH, formatPoints, formatPointsPrice } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
 export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdentity, hostIdentity, instanceIdentity, mcpConnectionIdentity, } from './instanceIdentity.js';
 export * from './utils/appUrls.js';

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { AgreementPartySide, AgreementParties, PrincipalPresentation, InboxDeliveryRef } from '@ziggs-ai/contracts';
 import type { InboxRequestChannel } from '@ziggs-ai/contracts';
+import type { InboxPartyKind } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
  *
@@ -368,7 +369,7 @@ export type MessageHandler = (text: string, metadata: MessageMetadata) => Promis
  */
 export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'request';
 /** The two mailbox owners. Agents own no mailbox — they read through grants. */
-export type InboxPartyKind = 'human' | 'org';
+export type { InboxPartyKind };
 /** One mailbox this reader's merged view includes. */
 export interface InboxSourceRef {
     partyId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "^0.9.0",
+    "@ziggs-ai/contracts": "^0.21.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [