@ziggs-ai/api-client 0.28.1 → 0.29.0

package/dist/capabilities/context.js

@@ -1,3 +1,4 @@
+import { presentResourceActions } from './resourceActions.js';
 import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
 import { ContextOpenClient } from '../http/ContextOpenClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
@@ -306,9 +307,16 @@ function presentOpenResult(result, env) {
     });
     return {
         ...result,
-        actions: result.access.continuation?.request ? [requestAccessAction(result.access.continuation.request, env)] : result.ref.kind === 'artifact' && result.outcome === 'unreadable' ? [requestAccessAction({ scopeKind: 'artifact', scopeId: result.ref.id, permission: 'read', durationHours: 24 }, env)] : resumeActions,
+        actions: result.actions
+            ? [...presentResourceActions(result.actions, env.surface),
+                ...resumeActions.map(a => ({ ...a, action: 'resume', state: 'not_evaluated' }))]
+            : result.access.continuation?.request
+                ? [requestAccessAction(result.access.continuation.request, 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,
-        ...(result.ref.kind === 'artifact' && result.outcome !== 'ok' ? {
+        ...(!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.`,
         } : {}),
     };
@@ -318,8 +326,8 @@ export const openCapability = {
     names: { sdk: 'open', mcp: 'ziggs_open' },
     title: 'Open a returned resource',
     descriptions: {
-        sdk: 'Open an artifact, chat, task, or agreement you were given an id for. Pass exactly one of artifactId, chatId, taskId, agreementId. Do not pick a grant id or reconstruct type/via — the server resolves the read path and rechecks authorization every time. Read-only: this never requests access or records an approval. Reading is not reply, share, delegate, approve, or original-file download. Extraction pending/failed is not an empty document.',
-        mcp: 'Open an artifact, chat, task, or agreement from an ordinary returned id (inbox, find, task result). Pass exactly one of artifactId, chatId, taskId, agreementId. Do not call ziggs_grant_list first, do not pick a grant id, and do not reconstruct type/via — the server resolves the path and rechecks every call. A saved id is not authority. Read-only: never requests access or approves. Hidden and unknown look the same; a discoverable-but-unreadable row names an owner-decision, which this call does not execute. Text access is not a file download. Extraction pending/failed is not an empty document.',
+        sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document.',
+        mcp: 'Read a returned artifact, chat, task, or agreement: pass exactly one corresponding id. No preliminary grant lookup. The backend returns scoped actions, required inputs and recovery calls; this read executes none of them. Hidden and unknown look the same. Extraction pending/failed is not an empty document.',
     },
     annotation: 'read-only',
     params: {
@@ -341,8 +349,8 @@ export const accessExplainCapability = {
     names: { sdk: 'access_explain', mcp: 'ziggs_access_explain' },
     title: 'Explain access to a resource',
     descriptions: {
-        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Says whether you can read, and that reading does not imply reply, share, delegate, approve, or download. Does not return content and does not request or approve anything.',
-        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Names the owner-decision route when you cannot read a discoverable resource; this call never executes that request. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
+        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Returns scoped action states, required inputs and recovery calls. Does not return content and does not request or approve anything.',
+        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Returns scoped actions and recovery calls; this call never executes them. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
     },
     annotation: 'read-only',
     params: OPEN_ID_PARAMS,

package/dist/capabilities/index.d.ts

@@ -18,3 +18,4 @@ export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapabilit
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, type SendPresentation, } from './chat.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
+export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/index.js

@@ -18,3 +18,4 @@ export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapabilit
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';
 export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
+export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/nextCall.d.ts

@@ -4,7 +4,9 @@ import type { CapabilityDefinition, CapabilityEnv } from './types.js';
  * One next step: the tool the calling surface registers, any args already
  * known, and why.
  *
- * Ready means a caller can run it verbatim. Incomplete means a required
+ * Ready means the call has complete arguments and no declared hold; it is
+ * not an authorization decision. The server checks permission on execution.
+ * Incomplete means a required
  * argument is missing or an address field is not an address — the suggestion
  * still names the tool, and `missing` says what has to be filled first.
  *
@@ -19,7 +21,7 @@ export interface NextCall {
     args?: Record<string, unknown>;
     /** One clause: what running this achieves, or what is still missing. */
     why: string;
-    /** True only when every required argument is present and addressable. */
+    /** Arguments are complete and no hold is declared; does not prove authority. */
     ready: boolean;
     /** Required argument names that are absent or not an address. */
     missing?: readonly string[];

package/dist/capabilities/resourceActions.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceAction } from '../http/ContextOpenClient.js';
+/** Bind canonical tool names without changing the backend's decision or scope. */
+export declare function presentResourceActions(actions: ResourceAction[], surface: 'sdk' | 'mcp'): ResourceAction[];

package/dist/capabilities/resourceActions.js

@@ -0,0 +1,9 @@
+/** Bind canonical tool names without changing the backend's decision or scope. */
+export function presentResourceActions(actions, surface) {
+    const toolName = (name) => surface === 'mcp' && !name.startsWith('ziggs_') ? `ziggs_${name}` : name;
+    const call = (value) => ({ ...value, tool: toolName(value.tool) });
+    return actions.map(action => ({ ...action,
+        ...(action.tool ? { tool: toolName(action.tool) } : {}),
+        ...(action.recovery ? { recovery: call(action.recovery) } : {}),
+    }));
+}

package/dist/http/AgreementClient.d.ts

@@ -190,8 +190,8 @@ export declare function resolveMyPendingApprovalPartyId(agreement: Agreement, op
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
  *
- * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
- * principal when approving as human, delegate agent id when impersonating.
+ * Use the partyId from the server's approvalAction. Agents need covering
+ * approval authority even for their own slot; the server rechecks it on PUT.
  * Canonical for hire, service, link, and request proposals.
  */
 export declare function approveAgreementAsParty(agreementId: string, partyId: string, status: 'approved' | 'rejected', creds: Creds): Promise<Agreement>;

package/dist/http/AgreementClient.js

@@ -53,6 +53,7 @@ export function linkSummary(a) {
         // chat with. Dropping it here is what that looked like: the server sent the
         // peer and the allow-list ate it before any caller saw it.
         ...(a.peer ? { peer: a.peer } : {}),
+        ...(a.approvalAction ? { approvalAction: a.approvalAction } : {}),
         ...(a.description ? { description: a.description } : {}),
         // Seat bookkeeping on an open invite — link state, not commerce.
         ...(a.linkInvite ? { linkInvite: a.linkInvite } : {}),
@@ -222,7 +223,11 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     if (!agreement) {
         throw new Error(`Agreement ${agreementId} not found`);
     }
-    const partyId = resolveMyPendingApprovalPartyId(agreement, {
+    const approval = agreement.approvalAction;
+    if (approval && (approval.state !== 'available' || !approval.partyId)) {
+        throw new Error(`${approval.explanation}${opts.appUrl ? ` Review: ${opts.appUrl}` : ''}`);
+    }
+    const partyId = approval?.partyId ?? resolveMyPendingApprovalPartyId(agreement, {
         ownerUserId: opts.ownerUserId,
         agentId: creds.agentId,
     });
@@ -288,8 +293,8 @@ export function resolveMyPendingApprovalPartyId(agreement, opts) {
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
  *
- * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
- * principal when approving as human, delegate agent id when impersonating.
+ * Use the partyId from the server's approvalAction. Agents need covering
+ * approval authority even for their own slot; the server rechecks it on PUT.
  * Canonical for hire, service, link, and request proposals.
  */
 export async function approveAgreementAsParty(agreementId, partyId, status, creds) {

package/dist/http/ContextOpenClient.d.ts

@@ -14,16 +14,25 @@ export interface ContextOpenBody {
     after?: string;
     limit?: number;
 }
-export interface ContextOpenAbilities {
-    read: boolean;
-    reply: boolean;
-    share: boolean;
-    delegate: boolean;
-    approve: boolean;
-    download: boolean;
+/** Backend-evaluated action, scoped to a resource. Never a permission token. */
+export interface ResourceActionCall {
+    tool: string;
+    args: Record<string, unknown>;
+    required?: string[];
+}
+export interface ResourceAction extends Partial<ResourceActionCall> {
+    action: string;
+    state: 'available' | 'needs_decision' | 'unavailable' | 'not_evaluated';
+    reasonCode?: string;
+    reason?: unknown;
+    scope?: {
+        kind: string;
+        id: string;
+        agreementId?: string;
+    };
+    recovery?: ResourceActionCall;
 }
 export interface ContextOpenAccess {
-    abilities: ContextOpenAbilities;
     summary: string;
     document?: {
         empty: boolean;
@@ -42,6 +51,8 @@ export interface ContextOpenAccess {
     };
 }
 export interface ContextOpenResult {
+    /** Optional for servers predating resource action projections. */
+    actions?: ResourceAction[];
     outcome: ContextOpenOutcome;
     ref: ContextOpenRef;
     access: ContextOpenAccess;

package/dist/http/ContextReadClient.d.ts

@@ -57,6 +57,8 @@ export interface ContextSnapshotParticipant {
     [key: string]: unknown;
 }
 export interface ContextSnapshotResult {
+    /** Server-resolved orientation; writes recheck authority. */
+    workBrief?: Record<string, unknown>;
     work?: Record<string, unknown>;
     history: unknown[];
     agreements: unknown[];

package/dist/http/index.d.ts

@@ -10,7 +10,7 @@ export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, List
 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 type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBody, ResourceAction, ResourceActionCall, ContextOpenAccess, ContextOpenResult, ContextExplainResult, } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';

package/dist/types.d.ts

@@ -176,6 +176,11 @@ export interface AgreementApprovalEntry {
     heldReason?: string | null;
 }
 export interface Agreement {
+    approvalAction?: {
+        state: 'available' | 'needs_decision' | 'unavailable';
+        partyId?: string;
+        explanation: string;
+    };
     agreementId: string;
     parentAgreementId?: string | null;
     rootAgreementId?: string | null;

package/package.json

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