@ziggs-ai/api-client 0.38.2 → 0.39.1

package/dist/http/agreementFlows.d.ts

@@ -1,4 +1,4 @@
-import { type ClaimedKind, type ClaimOptions, type ClaimRoom, type ProposeTerms } from './AgreementClient.js';
+import { type ClaimedKind, type ClaimOptions, type ProposeTerms } from './AgreementClient.js';
 import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 /**
  * one propose grammar. Direct, broadcast (request and standing
@@ -13,7 +13,7 @@ import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 export interface UnifiedProposeInput extends ProposeTerms {
     proposedTo: string;
     /** Required on direct proposals; optional on broadcasts/links. */
-    chatId?: string;
+    addressId?: string;
     engagementKind?: EngagementKind;
 }
 export type ProposeShape = 'direct' | 'request' | 'offer';
@@ -38,5 +38,4 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
 export declare function claimOpenAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     agreement: Agreement;
     kind: ClaimedKind;
-    room?: ClaimRoom;
 }>;

package/dist/http/agreementFlows.js

@@ -2,7 +2,7 @@ import { claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementC
 import { publishOffer } from './MarketplaceClient.js';
 import { isBroadcastTarget, } from '../types.js';
 export async function proposeUnified(input, creds) {
-    const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
+    const { proposedTo, addressId, engagementKind, providerId, ...terms } = input;
     if (!proposedTo)
         throw new Error('proposedTo is required (a user/agent id, or "everyone"/"org"/"company" to broadcast)');
     // The 'link' arm is gone. A link is not a proposal shape: it has no
@@ -34,7 +34,7 @@ export async function proposeUnified(input, creds) {
         // Buyer-broadcast: the claimer works, your side pays — an open request.
         const agreement = await proposeBroadcast({
             ...terms,
-            chatId: chatId ?? '',
+            addressId: addressId ?? '',
             engagementKind: engagementKind ?? 'service',
             audience,
         }, creds);
@@ -51,7 +51,7 @@ export async function proposeUnified(input, creds) {
         proposedTo,
         // Omitted rather than sent empty: an absent field says "no room", and an
         // empty string is one more fiction for the server to interpret.
-        ...(chatId ? { chatId } : {}),
+        ...(addressId ? { addressId } : {}),
         providerId: providerId?.trim() || proposedTo,
         engagementKind: engagementKind ?? 'service',
     }, creds);
@@ -74,8 +74,8 @@ export async function proposeUnified(input, creds) {
 export async function claimOpenAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
         throw new Error('agreementId is required');
-    const { agreement, kind, room } = await claimAgreement(agreementId, creds, opts);
+    const { agreement, kind } = await claimAgreement(agreementId, creds, opts);
     // A server that has not shipped the `kind` field yet still claims correctly;
     // 'request' is the shape the route has always handled.
-    return { agreement, kind: kind ?? 'request', ...(room ? { room } : {}) };
+    return { agreement, kind: kind ?? 'request' };
 }

package/dist/http/index.d.ts

@@ -2,13 +2,10 @@ export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
 export * from './agreementFlows.js';
-export * from './ChatClient.js';
-export { MessagesClient, messagesListUrl } from './MessagesClient.js';
-export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
-export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
+export { ArtifactsClient, artifactScope, 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, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotQuery, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextOpenClient, CONTEXT_OPEN_KINDS } from './ContextOpenClient.js';
 export type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBody, ResourceAction, ResourceActionCall, ContextOpenAccess, ContextOpenResult, ContextExplainResult, } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
@@ -37,3 +34,4 @@ export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds,
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from '../inboxAck.js';
 export { laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick, type ToolPickOption, type ToolPickAnswer, type PickTool } from './ToolPickClient.js';
+export * from './MessageRecordsClient.js';

package/dist/http/index.js

@@ -2,11 +2,9 @@ export * from './TaskClient.js';
 export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
 export * from './agreementFlows.js';
-export * from './ChatClient.js';
-export { MessagesClient, messagesListUrl } from './MessagesClient.js';
 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';
+// Artifact writes name their conversation or work; a lane is never one.
+artifactScope, 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';
@@ -28,3 +26,4 @@ export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds,
 // copy of a header nobody notices missing goes stale unseen.
 export { laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick } from './ToolPickClient.js';
+export * from './MessageRecordsClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -12,6 +12,9 @@ type AssistantHints = {
 };
 /** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
 export declare function withAssistantRequest<T>(hints: AssistantHints, run: () => T): Promise<Awaited<T>>;
+/** Start an autonomous callback with no inherited execution, attempt or assistant hints.
+ * This is an entry boundary, never a retry of a refused scoped operation. */
+export declare function withAutonomousRequest<T>(run: () => T): Promise<Awaited<T>>;
 export declare function assistantRequestHeaders(): Record<string, string>;
 /** A presentation routing key; it carries no authority. */
 export declare function laneUnderAgreement(laneId: string, agreementId?: string | null): string;

package/dist/http/operatorHeaders.js

@@ -1,19 +1,26 @@
 let assistantRequest;
 let assistantContextLoading;
-/** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
-export async function withAssistantRequest(hints, run) {
+async function requestContext() {
     assistantContextLoading ??= import('node:async_hooks').then(({ AsyncLocalStorage }) => {
         assistantRequest = new AsyncLocalStorage();
         return assistantRequest;
     });
-    const context = await assistantContextLoading;
-    // A workspace router adds its per-operation target inside the caller's
-    // session. Preserve that session without sharing it between concurrent calls.
+    return assistantContextLoading;
+}
+/** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
+export async function withAssistantRequest(hints, run) {
+    const context = await requestContext();
     return await context.run({ ...context.getStore(), ...hints, orgId: hints.orgId, resource: hints.resource }, run);
 }
+/** Start an autonomous callback with no inherited execution, attempt or assistant hints.
+ * This is an entry boundary, never a retry of a refused scoped operation. */
+export async function withAutonomousRequest(run) {
+    return await (await requestContext()).run({}, run);
+}
 export function assistantRequestHeaders() {
     const hints = assistantRequest?.getStore();
     return {
+        ...(hints?.executionContext?.attemptId ? { 'X-Ziggs-Attempt': hints.executionContext.attemptId } : {}),
         ...((hints?.executionContextId ?? hints?.executionContext?.contextId) ? { 'X-Ziggs-Execution': (hints?.executionContextId ?? hints?.executionContext?.contextId) } : {}),
         ...(hints?.orgId ? { 'X-Workspace-Id': hints.orgId } : {}),
         ...(hints?.resource ? { 'X-Ziggs-Resource': hints.resource } : {}),
@@ -49,6 +56,8 @@ export function withoutExecution(headers) {
     const out = { ...headers };
     delete out['X-Ziggs-Execution'];
     delete out['x-ziggs-execution'];
+    delete out['X-Ziggs-Attempt'];
+    delete out['x-ziggs-attempt'];
     return out;
 }
 /** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */

package/dist/inboxAck.d.ts

@@ -3,7 +3,7 @@ export interface InboxAckEnvelope {
     ackTo?: string | null;
     deliveries?: ReadonlyArray<{
         resourceId?: string | null;
-        responsibilityId?: string | null;
+        receiptId?: string | null;
         assigneeId?: string | null;
         outOfReach?: unknown;
         executionBlocked?: unknown;
@@ -12,7 +12,7 @@ export interface InboxAckEnvelope {
     }>;
     openRequestsAwaitingMe?: ReadonlyArray<{
         agreementId?: string | null;
-        responsibilityId?: string | null;
+        receiptId?: string | null;
         ts?: string | null;
     }>;
 }

package/dist/inboxAck.js

@@ -1,8 +1,8 @@
 export function inboxAckHandledIds(envelope, ownAgentId, ownAgentIds) {
     const mine = (id) => ownAgentIds ? ownAgentIds.includes(id ?? '') : ownAgentId ? id === ownAgentId : !!id;
     return [...new Set([
-            ...(envelope.deliveries ?? []).filter(d => mine(d.assigneeId) && !d.outOfReach && !d.executionBlocked).map(d => d.responsibilityId),
-            ...(envelope.openRequestsAwaitingMe ?? []).map(r => r.responsibilityId),
+            ...(envelope.deliveries ?? []).filter(d => mine(d.assigneeId) && !d.outOfReach && !d.executionBlocked).map(d => d.receiptId),
+            ...(envelope.openRequestsAwaitingMe ?? []).map(r => r.receiptId),
         ].filter((id) => !!id))];
 }
 export function inboxAckAllowed(envelope, opts = {}) {

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export type { DelegateEnv, ResolvedDelegateCreds, } from './shared/delegateCreds
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxPeek, InboxReadOptions, } from './types.js';
-export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, ClaimRoom, } from './http/AgreementClient.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxPlanAckRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxPeek, InboxReadOptions, } from './types.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
 export { decisionWords, speakableActor } from './decisionWords.js';
 export type { DecisionOutcome, DecisionWords, DecisionWordsInput, } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
@@ -31,9 +31,9 @@ export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, forma
 export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, EngagementTaskHint, ContactPathInput, FormationInput, GraphHonesty, HireTermsHonesty, WaitingOn, } from './engagementGuide.js';
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
 export { AssistantConnectionClient, type AssistantWorkspace, type McpEventStatus, } from './http/AssistantConnectionClient.js';
-export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
+export { withAssistantRequest, withAutonomousRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef, type HandleKind } from './handles.js';
 export { describeOperationError, type OperationError } from './shared/operationError.js';
 export { withWorkExecution, withWorkExecutionId, currentWorkExecution, withoutExecution } from './http/operatorHeaders.js';
 export { deliveryHandlingId, type WorkExecutionContext, type WorkPositionView } from '@ziggs-ai/contracts';
-export { validateWorkExecution } from './http/ExecutionContextClient.js';
+export { validateWorkExecution, prepareWorkExecution, runWorkExecution } from './http/ExecutionContextClient.js';

package/dist/index.js

@@ -28,10 +28,10 @@ export { sessionOrientation, } from './sessionOrientation.js';
 export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
 export { AssistantConnectionClient, } from './http/AssistantConnectionClient.js';
-export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
+export { withAssistantRequest, withAutonomousRequest, assistantRequestHeaders } from './http/operatorHeaders.js';
 // Short handles: T…, A…, C…, F… (task, agreement, chat, artifact).
 export { HANDLE_ALPHABET, findHandles, looksLikeHandle, parseHandle, parseRef } from './handles.js';
 export { describeOperationError } from './shared/operationError.js';
 export { withWorkExecution, withWorkExecutionId, currentWorkExecution, withoutExecution } from './http/operatorHeaders.js';
 export { deliveryHandlingId } from '@ziggs-ai/contracts';
-export { validateWorkExecution } from './http/ExecutionContextClient.js';
+export { validateWorkExecution, prepareWorkExecution, runWorkExecution } from './http/ExecutionContextClient.js';

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, COMPANY_AGREEMENT_TARGET, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, type AgreementPartySide, type AgreementParties, type AgreementStatusValue, type BroadcastAudience, type InboxDeliveryRef, type InboxPartyKind, type InboxRequestChannel, type PrincipalPresentation, type TaskStateValue } from '@ziggs-ai/contracts';
+import { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, COMPANY_AGREEMENT_TARGET, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, type AgreementPartySide, type AgreementParties, type AgreementStatusValue, type BroadcastAudience, type InboxDeliveryRef, type InboxPartyKind, type InboxPlanAckChannel, type InboxRequestChannel, type PrincipalPresentation, type TaskStateValue } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
  *
@@ -299,57 +299,6 @@ export declare function isValidContentType(contentType: string, entryType: strin
 export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';
 /** Display + entitlement face for a principal on the message/roster wire. */
 export type { PrincipalPresentation };
-export interface MessageMetadata {
-    chatId: string;
-    /** Stable id for dedup across push + inbox catch-up. */
-    messageId?: string;
-    userId: string;
-    sender: {
-        id: string;
-        type?: string;
-        presentation?: PrincipalPresentation | null;
-        /** Absent when the viewer is masked (persona layer). */
-        underAgreementId?: string | null;
-        presentedAs?: string | null;
-    };
-    senderId: string;
-    senderType?: string;
-    receiver?: {
-        id: string;
-        presentation?: PrincipalPresentation | null;
-    } | null;
-    receiverId?: string | null;
-    /**
-     * Message-level presentation stamp when the backend attaches one
-     * (same shape as sender.presentation). Prefer sender.presentation.
-     */
-    presentation?: PrincipalPresentation | null;
-    entryType?: string;
-    contentType?: string;
-    taskId?: string | null;
-    /**
-     * Optional task / agreement snapshot pinned by the backend on
-     * `task.notify.chat` / `agreement.notify.direct` traffic. The agent SDK's
-     * `normalizeIncomingEvent` reads `metadata.task` to upgrade structured
-     * task notifications into `task_result` events (so executors see
-     * `task-assigned` outcomes when the orchestrator calls `task_create`),
-     * and maps explicit wire `operation` + `agreementId` lifecycle fields
-     * into `agreement_lifecycle` events for proposal approve/reject.
-     */
-    task?: Record<string, unknown> | null;
-    agreement?: Record<string, unknown> | null;
-    operation?: string | null;
-    agreementId?: string | null;
-    /**
-     * Message send time from the wire payload. The live-path inbox
-     * watermark ack (Agent, P4) needs it — without a timestamp the
-     * ack never fires and catch-up re-delivers the chat's whole backlog after a
-     * host eviction, re-running already-answered goals.
-     */
-    timestamp?: string;
-    sentTimestamp?: string;
-}
-export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;
 /**
  * What a delivery can be about. A closed union, not a comment: a consumer that
  * dispatches on `kind` (the MCP read plan) is only safe if the compiler can tell
@@ -372,7 +321,7 @@ export interface InboxSourceRef {
 export type { InboxDeliveryRef };
 /** Message/artifact deliveries folded by chat, so you can open chats directly. */
 export interface InboxChatNews {
-    chatId: string;
+    addressId: string;
     count: number;
     latestAt: string;
 }
@@ -453,7 +402,17 @@ export interface InboxTaskRef {
  * exact-match triage with zero LLM tokens before any wake.
  */
 export type { InboxOpenRequestRef as InboxRequestRef } from '@ziggs-ai/contracts';
-export interface InboxEnvelope extends InboxRequestChannel {
+/**
+ * A task whose plan waits on this reader's acknowledgement: work the reader's
+ * side pays for. A plan on work the reader was hired to do is the hirer's and
+ * is not listed.
+ */
+export type { InboxPlanAckRef } from '@ziggs-ai/contracts';
+/**
+ * `planAcksAwaitingMe` / `truncatedPlanAcks` are absent on older servers;
+ * read them as empty.
+ */
+export interface InboxEnvelope extends InboxRequestChannel, Partial<InboxPlanAckChannel> {
     asOf: string;
     /**
      * The mailboxes this reader's view merges — its owner's, plus whatever
@@ -498,6 +457,7 @@ export interface InboxEnvelope extends InboxRequestChannel {
      */
     ackTo: string | null;
     /** Open tasks assigned to this agent — the work channel. */
+    answersAwaitingMe?: InboxDeliveryRef[];
     tasksAwaitingMe: InboxTaskRef[];
     truncatedTasks: number;
     proposalsAwaitingMe: InboxProposalRef[];
@@ -545,7 +505,7 @@ export interface InboxChangesResult {
     cursor: string;
     expiresAt: string;
     hasMore: boolean;
-    deliveries: Array<Pick<InboxDeliveryRef, 'eventId' | 'kind' | 'resourceId' | 'chatId' | 'taskId' | 'agreementId' | 'assigneeId' | 'needsHuman' | 'ts'> & {
+    deliveries: Array<Pick<InboxDeliveryRef, 'eventId' | 'kind' | 'resourceId' | 'addressId' | 'taskId' | 'agreementId' | 'assigneeId' | 'needsHuman' | 'ts'> & {
         orgId?: string | null;
     }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.38.2",
+  "version": "0.39.1",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -31,7 +31,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "^0.33.1",
+    "@ziggs-ai/contracts": "0.42.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [

package/dist/capabilities/chat.d.ts

@@ -1,43 +0,0 @@
-import { type SendChatMessageResult } from '../http/ChatClient.js';
-import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
-import { type WorkContext } from './nextCall.js';
-export interface SendPresentation {
-    ok: true;
-    chatId: string;
-    messageId: string;
-    /** Keep the server's delivery guidance on every client surface. */
-    message?: string;
-    /** What the server did with this send, stated so it cannot be over-read. */
-    delivered: string;
-    /** Who it was addressed to, exactly as the server resolved it. */
-    to?: {
-        id: string;
-        type: string;
-    };
-    workContext?: WorkContext;
-    delivery?: SendChatMessageResult['delivery'];
-}
-/**
- * Present a send as what it is: a message that now exists, addressed to
- * somebody, which may or may not wake anyone.
- *
- * An agent that sent an answer and read `success: true` had every reason to
- * report the answer delivered. Three different things hide behind that word.
- * The message exists — that much is certain. Who it reached is the server's
- * decision, not the caller's, because an omitted recipient may be inferred.
- * Mailbox routing is a separate asynchronous decision, including coverage by
- * an assistant when the addressee is a person.
- *
- * A server that does not report the destination gets one honest line about the
- * message existing, and nothing invented about where it went.
- */
-export declare function presentSendResult(result: SendChatMessageResult, env: CapabilityEnv): SendPresentation;
-/**
- * the decided chat surface for agents: chat_open only.
- * There is deliberately NO chat-listing tool on the SDK: taking part in a room
- * IS a grant on it, so "what chats can I see" is already answered by grant_list
- * scopeKind=chat. MCP keeps its rich session-UX lister
- * (ziggs_chat_list) for humans in Cursor/Claude.
- */
-export declare const openConversationCapability: CapabilityDefinition;
-export declare const CHAT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/chat.js

@@ -1,196 +0,0 @@
-import { openConversation } from '../http/ChatClient.js';
-import { chatAppUrl } from '../utils/appUrls.js';
-import { fullCreds } from './types.js';
-import { webAppOrigin } from './links.js';
-import { workContextFromEnv } from './nextCall.js';
-/**
- * Present a send as what it is: a message that now exists, addressed to
- * somebody, which may or may not wake anyone.
- *
- * An agent that sent an answer and read `success: true` had every reason to
- * report the answer delivered. Three different things hide behind that word.
- * The message exists — that much is certain. Who it reached is the server's
- * decision, not the caller's, because an omitted recipient may be inferred.
- * Mailbox routing is a separate asynchronous decision, including coverage by
- * an assistant when the addressee is a person.
- *
- * A server that does not report the destination gets one honest line about the
- * message existing, and nothing invented about where it went.
- */
-export function presentSendResult(result, env) {
-    const workContext = workContextFromEnv(env);
-    const delivery = result.delivery;
-    const base = {
-        ok: true,
-        chatId: result.chatId,
-        messageId: result.messageId,
-        ...(result.message ? { message: result.message } : {}),
-        ...(workContext ? { workContext } : {}),
-    };
-    if (!delivery) {
-        return {
-            ...base,
-            delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}. Accepted is not read: nothing here says anyone has seen it.`,
-        };
-    }
-    const destination = delivery.broadcast
-        ? 'the humans in the room, not one addressee'
-        : `${delivery.to.id} (${delivery.to.type})`;
-    // What counted it, in the server's words: a stranger's free messages with a
-    // listed agent run out, and the person writing needs to know before they do.
-    const counted = result.coverage?.message ? ` ${result.coverage.message}` : '';
-    const routing = delivery.broadcast
-        ? "This human-only broadcast does not wake assistants or stand-ins. If you need a reply, send a new message in this same chat to the person's returned participant id (receiverId), with a fresh message id or idempotency key. Existing conversation permissions still apply."
-        : delivery.reachable
-            ? `Assigned to ${delivery.assignee ?? 'nobody'}; reachable: ${delivery.reachable}${delivery.reason ? ` (${delivery.reason})` : ''}.${delivery.lastRead ? ` Last inbox read: ${delivery.lastRead}.` : ''}`
-            : 'Mailbox routing is unconfirmed; a person may be covered by an assistant.';
-    return {
-        ...base,
-        delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}, addressed to ${destination}. ${routing} Accepted is not read and does not confirm a wake or reply.${counted}`,
-        to: delivery.to,
-        delivery,
-    };
-}
-/**
- * the decided chat surface for agents: chat_open only.
- * There is deliberately NO chat-listing tool on the SDK: taking part in a room
- * IS a grant on it, so "what chats can I see" is already answered by grant_list
- * scopeKind=chat. MCP keeps its rich session-UX lister
- * (ziggs_chat_list) for humans in Cursor/Claude.
- */
-export const openConversationCapability = {
-    key: 'chat_open',
-    names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
-    title: 'Open, invite to, or resume a conversation',
-    descriptions: {
-        sdk: 'Open a conversation or explicitly invite people to a room. To resume admission of an existing hire, pass only chatId and agreementId; this uses the same recovery as the room UI and never hires or charges again. participantId opens/reuses your person’s conversation with one person or agent, the same room each of their agents finds; newChat opens a separate subject, which can take a name. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
-    },
-    annotation: 'write',
-    params: {
-        participantId: {
-            type: 'string',
-            description: 'Known user or agent id from search, a directory, a chat, or an agreement. For a teammate or a linked person, their user id, not an agent of theirs. No existing chat is required; do not guess ids.',
-        },
-        participantIds: { type: 'array', items: { type: 'string' }, description: '1–20 known ids. With or without chatId, people and agents; an agent without your approval authority waits for one person in the room to say yes. Use instead of participantId. Each invitation is authorized separately.' },
-        chatId: { type: 'string', description: 'Existing room. With participantIds: invite into it. With agreementId only: resume the approved hire admission without another hire or charge.' },
-        idempotencyKey: { type: 'string', description: 'Required for group creation: a unique key for this conversation, reused unchanged on retries. A different participant set needs a new key.' },
-        name: { type: 'string', description: 'Name for a new group or a newChat room, 1–80 characters. Pair rooms and team channels take no name. A retry of the same idempotencyKey keeps the first name. Rename later is PATCH /chats/:chatId by someone who can admit people.' },
-        createIfMissing: { type: 'boolean', description: 'Set false to reuse only an existing room with this participant. A missing room is refused without creating a replacement.' },
-        newChat: {
-            type: 'boolean',
-            description: 'Open a separate chat even though one is already open with the named participants. ' +
-                'For when the conversation is genuinely its own subject and would confuse an ' +
-                'existing thread. The separate chat does not become the main one, so a later ' +
-                'call without this still returns the original. Leave unset to continue where ' +
-                'you left off.',
-        },
-        agreementId: {
-            type: 'string',
-            description: 'With chatId: resume that existing hire’s room admission. Otherwise, the hire this open is the working room for. On a store-claim kickoff, pass the ' +
-                'claimed agreement id so the payer is stamped from-start in that room.',
-        },
-    },
-    needsAgentId: true,
-    handler: async (args, env) => {
-        if (args.chatId && args.agreementId) {
-            const result = await openConversation(args, fullCreds(env));
-            return {
-                ...result,
-                appUrl: chatAppUrl(webAppOrigin(env), result.chatId),
-                message: result.status === 'ready'
-                    ? 'The hired agent is admitted under this agreement. No new hire or charge was made.'
-                    : `Admission is still incomplete${result.reason ? `: ${result.reason}` : ''}. Retry this same call; do not claim again.`,
-            };
-        }
-        if (!args.participantId && !Array.isArray(args.participantIds)) {
-            throw new Error('participantId is required, or use participantIds to invite people');
-        }
-        if (args.participantIds !== undefined) {
-            if (args.participantId !== undefined || !Array.isArray(args.participantIds) ||
-                args.participantIds.length < 1 || args.participantIds.length > 20 ||
-                args.participantIds.some(id => typeof id !== 'string' || !id.trim())) {
-                throw new Error('Use participantIds containing 1–20 ids, without participantId');
-            }
-            if (!args.chatId && (typeof args.idempotencyKey !== 'string' || !args.idempotencyKey.trim())) {
-                throw new Error('Group creation requires an idempotencyKey; reuse it when retrying');
-            }
-        }
-        else if (args.chatId) {
-            throw new Error('chatId requires participantIds');
-        }
-        if (typeof args.name === 'string' && args.name.trim() && !Array.isArray(args.participantIds) && args.newChat !== true) {
-            throw new Error('A name is for a new group or a newChat room. Pair rooms take no name; the person is the name.');
-        }
-        const { chatId, reused, invited, name } = await openConversation({
-            ...(typeof args.participantId === 'string' ? { participantId: args.participantId } : {}),
-            ...(Array.isArray(args.participantIds) ? { participantIds: args.participantIds } : {}),
-            ...(typeof args.chatId === 'string' ? { chatId: args.chatId } : {}),
-            ...(typeof args.idempotencyKey === 'string' ? { idempotencyKey: args.idempotencyKey } : {}),
-            ...(args.newChat === true ? { newChat: true } : {}),
-            ...(typeof args.createIfMissing === 'boolean' ? { createIfMissing: args.createIfMissing } : {}),
-            ...(typeof args.agreementId === 'string' && args.agreementId ? { agreementId: args.agreementId } : {}),
-            ...(typeof args.name === 'string' && args.name.trim() ? { name: args.name.trim() } : {}),
-        }, fullCreds(env));
-        const agentId = fullCreds(env).agentId;
-        const { people, pending } = roomRoster(args, invited, agentId);
-        const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
-        const grantNote = `Use ${lister} with scopeKind ["chat"] to inspect your room grants. Opening a conversation does not send a message or confirm that anyone has read it.`;
-        // 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.
-        // A new group that named agents reports each of them too.
-        const created = reused === false ? 'Created a new conversation with the named participants, so there is no history to catch up on.' : null;
-        const outcomeNote = args.chatId
-            ? inviteNote(invited)
-            : created && invited?.length
-                ? `${created} ${inviteNote(invited)}`
-                : reused === true
-                    ? 'Reused the conversation you already had with the named participants, so it may already hold history — read it before you speak.'
-                    : reused === false
-                        ? 'Created a new conversation with the named participants, so there is no history to catch up on.'
-                        : 'Conversation is open (or reused).';
-        return {
-            chatId,
-            appUrl: chatAppUrl(webAppOrigin(env), chatId),
-            ...(agentId ? { actingAgentId: agentId } : {}),
-            people,
-            pending,
-            ...(typeof reused === 'boolean' ? { reused } : {}),
-            ...(name ? { name } : {}),
-            ...(invited ? { invited } : {}),
-            note: `${outcomeNote} ${grantNote}`,
-        };
-    },
-};
-/** Ids this open knows are in the room, and ids still waiting for approval. */
-function roomRoster(args, invited, agentId) {
-    const named = Array.isArray(args.participantIds)
-        ? args.participantIds.filter((id) => typeof id === 'string' && id.trim().length > 0).map((id) => id.trim())
-        : typeof args.participantId === 'string' && args.participantId.trim()
-            ? [args.participantId.trim()]
-            : [];
-    const pending = (invited ?? []).filter((row) => row.status === 'pending').map((row) => row.id);
-    const waiting = new Set(pending);
-    const here = (invited ?? []).filter((row) => row.status !== 'pending').map((row) => row.id);
-    const people = [...new Set([...named.filter((id) => !waiting.has(id)), ...here, ...(agentId ? [agentId] : [])])];
-    return { people, pending };
-}
-/** Say what happened to each invited id, so the agent reports it truthfully. */
-function inviteNote(invited) {
-    if (!invited?.length) {
-        return 'The named people can participate in this room. Their history access remains bounded by their grants.';
-    }
-    const ids = (status) => invited.filter((row) => row.status === status).map((row) => row.id);
-    const parts = [];
-    if (ids('added').length)
-        parts.push(`Added: ${ids('added').join(', ')}.`);
-    if (ids('already-here').length)
-        parts.push(`Already in the room: ${ids('already-here').join(', ')}.`);
-    if (ids('pending').length) {
-        parts.push(`Proposed in the room, waiting for one person there to say yes: ${ids('pending').join(', ')}. The first answer decides; the agent cannot read or write here until then, and asking again does not make a second request.`);
-    }
-    return `${parts.join(' ')} Invited people read from now on.`;
-}
-export const CHAT_CAPABILITIES = [openConversationCapability];

package/dist/capabilities/chatListFields.d.ts

@@ -1,14 +0,0 @@
-/**
- * Default `ziggs_chat_list` projection.
- *
- * The wire row carries three web-app rosters (`members`, `rosterSummary`,
- * `participantSummary`) and repeats the persona on each. The MCP default
- * keeps the people who actually receive (`participantSummary`) and drops the
- * other two unless `fields` asks for them.
- */
-export declare const CHAT_LIST_DEFAULT_FIELDS: readonly ["chatId", "name", "updatedAt", "lastMessage", "unreadCount", "participantSummary", "readable", "requestAccess"];
-/** Apply `fields`, or the MCP default when the caller omitted it. */
-export declare function projectChatListRows(chats: unknown[], fieldsRaw?: unknown): unknown[];
-export declare function utf8Bytes(value: unknown): number;
-/** Rough token count: 4 UTF-8 bytes per token, rounded up. */
-export declare function approxTokens(value: unknown): number;