@ziggs-ai/api-client 0.19.0 → 0.21.0

package/dist/http/ContextOpenClient.d.ts

@@ -0,0 +1,70 @@
+export declare const CONTEXT_OPEN_KINDS: readonly ["artifact", "chat", "task", "agreement"];
+export type ContextOpenKind = (typeof CONTEXT_OPEN_KINDS)[number];
+export type ContextOpenOutcome = 'ok' | 'unreadable' | 'hidden';
+export interface ContextOpenRef {
+    kind: ContextOpenKind;
+    id: string;
+}
+export interface ContextOpenBody {
+    artifactId?: string;
+    chatId?: string;
+    taskId?: string;
+    agreementId?: string;
+    cursor?: string;
+    after?: string;
+    limit?: number;
+}
+export interface ContextOpenAbilities {
+    read: boolean;
+    reply: boolean;
+    share: boolean;
+    delegate: boolean;
+    approve: boolean;
+    download: boolean;
+}
+export interface ContextOpenAccess {
+    abilities: ContextOpenAbilities;
+    summary: string;
+    document?: {
+        empty: boolean;
+        extractionStatus?: string | null;
+    };
+    continuation?: {
+        kind: 'owner_decision';
+        summary: string;
+    };
+}
+export interface ContextOpenResult {
+    outcome: ContextOpenOutcome;
+    ref: ContextOpenRef;
+    access: ContextOpenAccess;
+    workContext: {
+        laneId: string | null;
+    };
+    page?: {
+        type: string;
+        via: {
+            kind: string;
+            id: string;
+        };
+        items: unknown[];
+        hasMore: boolean;
+        nextCursor: string | null;
+        latestSequence?: string | null;
+    };
+}
+export type ContextExplainResult = Omit<ContextOpenResult, 'page'>;
+/**
+ * Open or explain a returned reference. The server resolves the read path;
+ * the caller does not send type, via, or a grant id.
+ */
+export declare class ContextOpenClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl?;
+    private readonly laneId?;
+    constructor(operatorKey: string, agentId?: string | undefined, baseUrl?: string | undefined, laneId?: string | undefined);
+    open(body: ContextOpenBody): Promise<ContextOpenResult>;
+    explain(body: ContextOpenBody): Promise<ContextExplainResult>;
+    private post;
+}

package/dist/http/ContextOpenClient.js

@@ -0,0 +1,52 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { pollSurfaceError } from '../shared/rateLimit.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+export const CONTEXT_OPEN_KINDS = [
+    'artifact',
+    'chat',
+    'task',
+    'agreement',
+];
+/**
+ * Open or explain a returned reference. The server resolves the read path;
+ * the caller does not send type, via, or a grant id.
+ */
+export class ContextOpenClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    laneId;
+    constructor(operatorKey, agentId, baseUrl, laneId) {
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl;
+        this.laneId = laneId;
+        if (!operatorKey)
+            throw new Error('ContextOpenClient: operatorKey is required');
+    }
+    async open(body) {
+        return this.post('/context/open', body);
+    }
+    async explain(body) {
+        return this.post('/context/access/explain', body);
+    }
+    async post(path, body) {
+        const filled = ['artifactId', 'chatId', 'taskId', 'agreementId'].filter((key) => typeof body[key] === 'string' && body[key].trim());
+        if (filled.length !== 1) {
+            throw new Error('ContextOpenClient: pass exactly one of artifactId, chatId, taskId, agreementId');
+        }
+        const url = `${this.baseUrl || getBackendUrl()}${path}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                ...buildOperatorHeaders(this.operatorKey, this.agentId, { 'Content-Type': 'application/json' }, this.laneId),
+            },
+            body: JSON.stringify(body),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw pollSurfaceError(`ContextOpenClient ${path}`, res, text);
+        }
+        return JSON.parse(text);
+    }
+}

package/dist/http/InboxClient.d.ts

@@ -36,6 +36,14 @@ export declare class InboxClient {
     ack(upTo: string, opts?: {
         handledResourceIds?: string[];
     }): Promise<InboxAckResult>;
+    /**
+     * Ack, and if the row still names a host that has already gone away,
+     * read once (that is what takes an expired inbox) and ack again.
+     * A second host-conflict is a live competitor and is rethrown unchanged.
+     */
+    ackOrTakeHost(upTo: string, opts?: {
+        handledResourceIds?: string[];
+    }): Promise<InboxAckResult>;
     /**
      * Drop this process's inbox host lease so another client can take
      * GET /inbox on its next read.

package/dist/http/InboxClient.js

@@ -1,5 +1,6 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+import { ApiError } from '../types.js';
 import { INBOX_HOST_CLAIMANT_HEADER, hostIdentity, } from '../instanceIdentity.js';
 /**
  * The doorbell, not the door: references addressed to this agent
@@ -96,6 +97,23 @@ export class InboxClient {
         }
         return JSON.parse(body);
     }
+    /**
+     * Ack, and if the row still names a host that has already gone away,
+     * read once (that is what takes an expired inbox) and ack again.
+     * A second host-conflict is a live competitor and is rethrown unchanged.
+     */
+    async ackOrTakeHost(upTo, opts = {}) {
+        try {
+            return await this.ack(upTo, opts);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.code !== 'INBOX_HOST_CONFLICT') {
+                throw err;
+            }
+            await this.getInbox();
+            return await this.ack(upTo, opts);
+        }
+    }
     /**
      * Drop this process's inbox host lease so another client can take
      * GET /inbox on its next read.

package/dist/http/TaskClient.d.ts

@@ -6,6 +6,8 @@ import { type Creds, type Task, type TaskState } from '../types.js';
 export interface TaskWriteConfirm {
     ok: true;
     taskId: string;
+    /** The agreement the task hangs under, when the server reports it. */
+    agreementId?: string;
     state: TaskState;
     updatedAt?: string;
     status?: string;

package/dist/http/TaskClient.js

@@ -37,6 +37,7 @@ function extractWriteConfirm(data) {
         return {
             ok: true,
             taskId: d['taskId'],
+            ...(typeof d['agreementId'] === 'string' ? { agreementId: d['agreementId'] } : {}),
             state: d['state'],
             ...(typeof d['updatedAt'] === 'string' || d['updatedAt'] instanceof Date
                 ? { updatedAt: String(d['updatedAt']) }

package/dist/http/index.d.ts

@@ -9,6 +9,8 @@ export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFA
 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, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
+export { ContextOpenClient, CONTEXT_OPEN_KINDS } from './ContextOpenClient.js';
+export type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBody, ContextOpenAbilities, ContextOpenAccess, ContextOpenResult, ContextExplainResult, } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';

package/dist/http/index.js

@@ -8,6 +8,7 @@ export { ArtifactsClient,
 // agreement lanes are not chats — callers scope artifact writes with this.
 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 { ContextOpenClient, CONTEXT_OPEN_KINDS } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';

package/dist/index.d.ts

@@ -18,3 +18,7 @@ export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId
 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';
+export { sessionOrientation, } from './sessionOrientation.js';
+export type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson, SessionContinuation, SessionOrientation, SessionOrientationInput, } from './sessionOrientation.js';
+export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
+export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, EngagementTaskHint, ContactPathInput, FormationInput, GraphHonesty, HireTermsHonesty, WaitingOn, } from './engagementGuide.js';

package/dist/index.js

@@ -18,3 +18,5 @@ export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId
 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';
+export { sessionOrientation, } from './sessionOrientation.js';
+export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';

package/dist/instanceIdentity.d.ts

@@ -25,7 +25,7 @@ export declare function cliHostIdentity(): string;
  *
  * Not the backend task's identity. That process serves every connected
  * assistant at once, so its own identity makes them one host and changes under
- * all of them on every deploy — a hosted read answering 409 for up to 330
+ * all of them on every deploy — a hosted read answering 409 for up to 220
  * seconds after each restart, and replicas refusing each other's agents.
  *
  * The key survives both. A token refresh re-signs the same `keyId`, so an

package/dist/instanceIdentity.js

@@ -4,7 +4,7 @@ import { decodeOperatorKeyClaims } from './shared/operatorKey.js';
  *
  * `X-Ziggs-Instance` decides inbox ownership: the first host to read acquires
  * an agent's whole inbox, a second host is refused with
- * `409 INBOX_HOST_CONFLICT` until the owner has stopped renewing for 330
+ * `409 INBOX_HOST_CONFLICT` until the owner has stopped renewing for 220
  * seconds, and an ack renews an owner but never acquires. A missing or
  * overlong value is `400 INBOX_HOST_REQUIRED`.
  *
@@ -71,7 +71,7 @@ export function cliHostIdentity() {
  *
  * Not the backend task's identity. That process serves every connected
  * assistant at once, so its own identity makes them one host and changes under
- * all of them on every deploy — a hosted read answering 409 for up to 330
+ * all of them on every deploy — a hosted read answering 409 for up to 220
  * seconds after each restart, and replicas refusing each other's agents.
  *
  * The key survives both. A token refresh re-signs the same `keyId`, so an

package/dist/sessionOrientation.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Who this session is, who it represents, and whether it can continue
+ * unattended. Built from the binding the caller already has. Does not
+ * read mail and does not take the inbox lease.
+ */
+export type InboxAckDriver = 'agent' | 'host';
+export type ContinuationKind = 'manual' | 'scheduled';
+export interface RepresentedPerson {
+    /** The human this agent acts for. Null when the key does not name one. */
+    id: string | null;
+    kind: 'user';
+}
+export interface SessionContinuation {
+    kind: ContinuationKind;
+    canScheduleWake: boolean;
+    summary: string;
+}
+export interface InboxHandling {
+    /** Who closes the inbox loop. Never both on the same identity. */
+    ackDriver: InboxAckDriver;
+    readAcquiresHost: true;
+    peekDoesNotAcquire: true;
+    peek: {
+        tool: string;
+        http: {
+            method: 'GET';
+            path: '/inbox/peek';
+        };
+    };
+}
+export interface SessionOrientation {
+    representedPerson: RepresentedPerson;
+    continuation: SessionContinuation;
+    inboxHandling: InboxHandling;
+    identity: {
+        agentId: string;
+        distinctFromBackgroundWorker: true;
+    };
+}
+export interface SessionOrientationInput {
+    agentId: string;
+    ownerUserId: string | null;
+    /** MCP assistants ack themselves. The hosted SDK host acks; the brain does not. */
+    surface: 'mcp' | 'sdk';
+}
+/**
+ * Facts a cold entry needs that `session.ownerId` never labelled: the
+ * represented person, whether this host can arm a wake, and who drives ack.
+ */
+export declare function sessionOrientation(input: SessionOrientationInput): SessionOrientation;

package/dist/sessionOrientation.js

@@ -0,0 +1,43 @@
+/**
+ * Who this session is, who it represents, and whether it can continue
+ * unattended. Built from the binding the caller already has. Does not
+ * read mail and does not take the inbox lease.
+ */
+const PEEK = {
+    tool: 'ziggs_inbox_peek',
+    http: { method: 'GET', path: '/inbox/peek' },
+};
+/**
+ * Facts a cold entry needs that `session.ownerId` never labelled: the
+ * represented person, whether this host can arm a wake, and who drives ack.
+ */
+export function sessionOrientation(input) {
+    const mcp = input.surface === 'mcp';
+    return {
+        representedPerson: {
+            id: input.ownerUserId,
+            kind: 'user',
+        },
+        continuation: mcp
+            ? {
+                kind: 'manual',
+                canScheduleWake: false,
+                summary: 'This MCP session has no wake_at. Continue by calling ziggs_inbox again — a scheduler in the host is the only unattended path.',
+            }
+            : {
+                kind: 'scheduled',
+                canScheduleWake: true,
+                summary: 'The hosted runtime can arm wake_at. The brain does not ack; the host owns the inbox loop.',
+            },
+        inboxHandling: {
+            ackDriver: mcp ? 'agent' : 'host',
+            readAcquiresHost: true,
+            peekDoesNotAcquire: true,
+            peek: PEEK,
+        },
+        identity: {
+            agentId: input.agentId,
+            distinctFromBackgroundWorker: true,
+        },
+    };
+}

package/dist/types.d.ts

@@ -216,6 +216,17 @@ export interface Agreement {
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
+    /**
+     * What `money.price` MEANS: `total` is the whole engagement, settled once;
+     * `per_task` is a rate charged as each task completes.
+     *
+     * The server has always stamped it (`terms.billing`, defaulting to
+     * `total`), and the marketplace row shows it, but the agreement an agent
+     * actually reads before working under it did not lift it. A rate then read as
+     * a total: one number, two meanings, and nothing on the row to tell them
+     * apart. Absent on rows written before the field existed, which read `total`.
+     */
+    billing?: 'total' | 'per_task';
     /**
      * Seat bookkeeping when this agreement is an open link invite. Each claim
      * takes a seat and mints its own child link, so one shared link produces N

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "socket.io-client": "^4.7.0",
-    "@ziggs-ai/contracts": "^0.7.1"
+    "@ziggs-ai/contracts": "^0.9.0"
   },
   "keywords": [
     "ziggs",