@ziggs-ai/api-client 0.19.0 → 0.20.0

package/dist/capabilities/nextCall.js

@@ -1,3 +1,126 @@
+/**
+ * Fields that name a party to reach. A `psn_` persona face is display state
+ * and must never be offered here — chat_open / chat_send refuse it, and the
+ * baseline's provider learned that only by being refused.
+ */
+const ADDRESS_FIELDS = ['participantId', 'to', 'receiverId'];
+/**
+ * Required arguments for the capability keys this helper is asked to emit.
+ * Kept next to the HTTP bindings so a ready call cannot advertise a schema
+ * the definition does not have. Keys we do not list here stay "no extra
+ * required args" — the caller already chose what to pre-fill. Tests pin
+ * these against live `CapabilityDefinition.params` for keys that have one.
+ */
+const REQUIRED_ARGS = {
+    chat_open: ['participantId'],
+    chat_send: ['chatId'],
+    agreement_claim: ['agreementId'],
+    agreement_respond: ['agreementId'],
+    introduction_redeem: ['token'],
+    context_issue_grant: ['holderId', 'scopeKind', 'scopeId'],
+};
+/**
+ * Published HTTP invocation per capability key. Paths match the api-client
+ * HTTP clients, not a restated OpenAPI list. Path params stay as `:name`
+ * until a ready arg fills them — an incomplete call must not invent an id.
+ */
+const HTTP_BINDINGS = {
+    chat_open: { method: 'POST', path: '/chats' },
+    chat_send: { method: 'POST', path: '/chats/:chatId/messages' },
+    introduction_list: { method: 'GET', path: '/introductions' },
+    introduction_mint: { method: 'POST', path: '/introductions' },
+    introduction_redeem: { method: 'POST', path: '/introductions/:token/redeem' },
+    agreement_claim: { method: 'POST', path: '/agreements/:agreementId/claim' },
+    agreement_respond: {
+        method: 'PUT',
+        path: '/agreements/:agreementId/approvals/:partyId',
+    },
+    marketplace_view: { method: 'GET', path: '/marketplace/offers' },
+    context_issue_grant: { method: 'POST', path: '/context/grants' },
+    open: { method: 'POST', path: '/context/open' },
+    access_explain: { method: 'POST', path: '/context/access/explain' },
+    inbox_peek: { method: 'GET', path: '/inbox/peek' },
+    link_list: { method: 'GET', path: '/agreements?engagementKind=link' },
+    link_propose: { method: 'POST', path: '/agreements/links' },
+};
+/**
+ * Intentional surface exclusions. A ready next call has to exist as a tool
+ * on the calling surface — SDK context exposes delegate, not a top-level
+ * issue grant (tool-surface-parity).
+ */
+const SURFACE_EXPOSURE = {
+    context_issue_grant: ['mcp'],
+};
+const MATERIAL_EFFECTS = {
+    agreement_claim: {
+        commitment: 'claiming makes you a party to the posted terms',
+        relationship: 'you become the open party on that broadcast',
+    },
+    agreement_respond: {
+        commitment: 'approve or reject binds your side; do not sign for a human whose slot this is',
+    },
+    introduction_redeem: {
+        relationship: 'a stranger redeem stages a link both humans must approve — it is not a live connection yet',
+    },
+    context_issue_grant: {
+        disclosure: 'issues a grant that widens who can read that scope',
+    },
+    link_propose: {
+        relationship: 'proposes a reach-only link; nothing is shared until they accept',
+    },
+    chat_open: {
+        disclosure: 'opening a room issues the other side a grant on it',
+    },
+};
+/** A persona face (`psn_…`) is display state, not a message address. */
+export function isPersonaFace(id) {
+    return typeof id === 'string' && id.startsWith('psn_');
+}
+/** Acting agent and lane from the env. Never a caller-chosen principal. */
+export function workContextFromEnv(env) {
+    const ctx = {
+        ...(env.creds.agentId ? { actingAgentId: env.creds.agentId } : {}),
+        ...(env.creds.laneId ? { laneId: env.creds.laneId } : {}),
+    };
+    return ctx.actingAgentId || ctx.laneId ? ctx : undefined;
+}
+function isFilled(value) {
+    return typeof value === 'string' ? value.trim().length > 0 : value != null;
+}
+function bindHttpPath(template, args) {
+    if (!args)
+        return template;
+    return template.replace(/:([A-Za-z][A-Za-z0-9]*)/g, (all, name) => {
+        const value = args[name];
+        if (typeof value === 'string' && value && !isPersonaFace(value)) {
+            return encodeURIComponent(value);
+        }
+        return all;
+    });
+}
+function toolName(env, capabilityKey) {
+    return env.surface === 'mcp' ? `ziggs_${capabilityKey}` : capabilityKey;
+}
+function requiredArgNames(capabilityKey, definition) {
+    if (definition) {
+        return Object.entries(definition.params)
+            .filter(([, param]) => param.required)
+            .map(([name]) => name);
+    }
+    return REQUIRED_ARGS[capabilityKey] ?? [];
+}
+function isKnownCapability(capabilityKey, definition) {
+    return (definition != null ||
+        capabilityKey in REQUIRED_ARGS ||
+        capabilityKey in HTTP_BINDINGS);
+}
+function isExposedOnSurface(capabilityKey, surface) {
+    const allowed = SURFACE_EXPOSURE[capabilityKey];
+    return allowed ? allowed.includes(surface) : true;
+}
+function effectsFor(capabilityKey, opts) {
+    return opts?.effects ?? MATERIAL_EFFECTS[capabilityKey];
+}
 /**
  * Build a next step naming the tool as the calling surface registers it.
  *
@@ -6,13 +129,107 @@
  * the 31 capability definitions follows that one rule, so the key is enough and
  * a caller cannot accidentally emit a name the surface does not have.
  */
-export function nextCall(env, capabilityKey, args, why) {
+export function nextCall(env, capabilityKey, args, why, opts) {
+    const ctx = workContextFromEnv(env);
+    const effects = effectsFor(capabilityKey, opts);
+    const extra = {
+        ...(effects ? { effects } : {}),
+        ...(ctx ? { workContext: ctx } : {}),
+    };
+    if (!isKnownCapability(capabilityKey, opts?.definition)) {
+        return {
+            tool: toolName(env, capabilityKey),
+            why: `${why} — this capability is not exposed as a next call`,
+            ready: false,
+            outcome: 'unavailable',
+            ...extra,
+        };
+    }
+    if (!isExposedOnSurface(capabilityKey, env.surface)) {
+        return {
+            tool: toolName(env, capabilityKey),
+            why: `${why} — not on this surface`,
+            ready: false,
+            outcome: 'unavailable',
+            ...extra,
+        };
+    }
+    const missing = [];
+    const filled = {};
+    for (const [key, value] of Object.entries(args ?? {})) {
+        if (!isFilled(value))
+            continue;
+        if (ADDRESS_FIELDS.includes(key) &&
+            isPersonaFace(value)) {
+            missing.push(key);
+            continue;
+        }
+        filled[key] = value;
+    }
+    for (const name of requiredArgNames(capabilityKey, opts?.definition)) {
+        if (!isFilled(filled[name])) {
+            if (!missing.includes(name))
+                missing.push(name);
+        }
+    }
+    const hold = opts?.hold;
+    const ready = missing.length === 0 && !hold;
+    const outcome = opts?.outcome ??
+        (hold
+            ? 'pending'
+            : missing.length === 0
+                ? 'ok'
+                : Object.keys(filled).length
+                    ? 'partial'
+                    : 'unavailable');
+    const http = HTTP_BINDINGS[capabilityKey];
+    const faceMissing = missing.some((name) => ADDRESS_FIELDS.includes(name));
+    const reason = hold && missing.length === 0
+        ? why
+        : !ready && faceMissing
+            ? `${why} — a next call for reaching a person names the user id or their agent, never a psn_ face`
+            : !ready
+                ? `${why} — missing ${missing.join(', ')}`
+                : why;
     return {
-        tool: env.surface === 'mcp' ? `ziggs_${capabilityKey}` : capabilityKey,
-        ...(args && Object.keys(args).length ? { args } : {}),
-        why,
+        tool: toolName(env, capabilityKey),
+        ...(Object.keys(filled).length ? { args: filled } : {}),
+        why: reason,
+        ready,
+        outcome,
+        ...(missing.length ? { missing } : {}),
+        ...(hold ? { hold } : {}),
+        ...(http
+            ? { http: { method: http.method, path: bindHttpPath(http.path, filled) } }
+            : {}),
+        ...extra,
     };
 }
+/**
+ * E23: messages, artifacts, and agreement prose are data. They cannot mint
+ * a server action. The only legal parse is "none".
+ */
+export function nextCallsFromUntrustedContent(_content) {
+    return [];
+}
+/**
+ * E22: a next call advertised against an earlier snapshot is stale when the
+ * row is no longer in the state that action assumed. Execution still has to
+ * hit the existing precondition (claim 400, respond refuse) — this is the
+ * client-side invalidation so a caller does not treat the suggestion as live.
+ */
+export function isStaleAdvertisedAction(advertised, current) {
+    const key = advertised.tool.replace(/^ziggs_/, '');
+    const status = current.status ?? '';
+    if (key === 'agreement_claim') {
+        return status.length > 0 && status !== 'open';
+    }
+    if (key === 'agreement_respond') {
+        return (status.length > 0 &&
+            !['open', 'proposed', 'pending'].includes(status));
+    }
+    return false;
+}
 /**
  * The other PRINCIPAL in a two-party agreement, from the perspective of
  * `selfId`.

package/dist/http/ArtifactsClient.d.ts

@@ -33,6 +33,37 @@ export interface ListArtifactsQuery {
  * typed now, where it was `unknown[]`.
  */
 export type ListArtifactsResult = ListReachableArtifactsResult;
+/**
+ * What `GET /artifacts/find` actually looked at.
+ *
+ * The whole reason the route is separate from the listing: a short answer from
+ * a search is ambiguous — nothing matched, or nothing was searched? Everything
+ * here exists so a caller can tell those apart without knowing anything about
+ * how artifacts are stored or which grants it holds. `completeness: 'complete'`
+ * means the query ran over the named arms with none cut short; it never means
+ * the artifact is not somewhere else in Ziggs.
+ */
+export interface FindArtifactsCoverage {
+    method: 'lexical';
+    /** The fields the query ran against — not the fields an artifact has. */
+    searchedFields: string[];
+    /** Reach arms that produced the candidate set, with their sizes. */
+    arms: Record<string, number>;
+    /** Arms that hit their cap, so older rows in them were never searched. */
+    truncatedArms: string[];
+    completeness: 'complete' | 'partial' | 'unknown';
+    limitations: string[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+export type FindArtifactsResult = ListReachableArtifactsResult & {
+    coverage: FindArtifactsCoverage;
+};
+export interface FindArtifactsOptions {
+    limit?: number;
+    /** Opaque `nextCursor` from a previous page, passed back verbatim. */
+    before?: string;
+}
 export interface WriteArtifactInput {
     text: string;
     /** Short list name. An upload defaults to filename when omitted. */
@@ -112,6 +143,22 @@ export declare class ArtifactsClient {
      */
     constructor(operatorKey: string, agentId?: string, laneId?: string);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
+    /**
+     * `GET /artifacts/find` — lexical search over the artifacts this agent can
+     * already reach: what it authored, what its readable containers hold, and
+     * what artifact grants it holds. Bounded by the active lane and shared-room
+     * containment, exactly as a point read is.
+     *
+     * This is not `list()` with a query string. `list()` answers "what is in this
+     * container"; a person's cross-container view lives behind `reach` arms that
+     * an agent has no business asking for. The server refuses `reach`,
+     * `authoredBy` and `chatId` here rather than ignoring them, so a narrowing
+     * filter can never be silently dropped — hence no options for them.
+     *
+     * The result always carries `coverage`. An empty `artifacts` is a statement
+     * about what was searched, not about the world.
+     */
+    find(query: string, opts?: FindArtifactsOptions): Promise<FindArtifactsResult>;
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the
      * `ContextWriter.recordEvent({ kind: 'thought' })` hack.

package/dist/http/ArtifactsClient.js

@@ -90,6 +90,39 @@ export class ArtifactsClient {
         }
         return (await res.json());
     }
+    /**
+     * `GET /artifacts/find` — lexical search over the artifacts this agent can
+     * already reach: what it authored, what its readable containers hold, and
+     * what artifact grants it holds. Bounded by the active lane and shared-room
+     * containment, exactly as a point read is.
+     *
+     * This is not `list()` with a query string. `list()` answers "what is in this
+     * container"; a person's cross-container view lives behind `reach` arms that
+     * an agent has no business asking for. The server refuses `reach`,
+     * `authoredBy` and `chatId` here rather than ignoring them, so a narrowing
+     * filter can never be silently dropped — hence no options for them.
+     *
+     * The result always carries `coverage`. An empty `artifacts` is a statement
+     * about what was searched, not about the world.
+     */
+    async find(query, opts = {}) {
+        const q = query?.trim();
+        if (!q) {
+            throw new Error('ArtifactsClient.find: a query is required — find searches what you can reach, it does not list it');
+        }
+        const url = new URL(`${getBackendUrl()}/artifacts/find`);
+        url.searchParams.set('q', q);
+        if (opts.limit != null)
+            url.searchParams.set('limit', String(opts.limit));
+        if (opts.before)
+            url.searchParams.set('before', opts.before);
+        const res = await fetch(url.toString(), { headers: this._headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throwApiError(res, body, `findArtifacts failed: ${res.status} ${res.statusText}`);
+        }
+        return (await res.json());
+    }
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the
      * `ContextWriter.recordEvent({ kind: 'thought' })` hack.

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,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 type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson, SessionContinuation, SessionOrientation, SessionOrientationInput, } from './sessionOrientation.js';

package/dist/index.js

@@ -18,3 +18,4 @@ 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';

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;