@ziggs-ai/api-client 0.30.2 → 0.31.0

package/README.md

@@ -106,7 +106,7 @@ Cross-org inbox and chat payloads mask counterparties behind presentation faces:
 
 - Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org — not `requesterAgentId`.
 - Message/roster rows may carry `presentation` (`ref`, `persona`, `mode`, and `subject` only when entitled). Masked senders omit `underAgreementId` / `presentedAs`.
-- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may echo an `rpb_*` as `receiverId` — the backend resolves it in-room.
+- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may name a masked party by its `rpb_*` as `receiverId` — the backend resolves it in-room. Leave the receiver out to write back in the room.
 
 Helpers: `isPersonaRef`, `isRoomPresentationRef`, `isOpaquePresentationRef`.
 

package/dist/capabilities/context.js

@@ -1,3 +1,4 @@
+import { isContextAccessRequest } from '../shared/contextAccessRequest.js';
 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';
@@ -65,7 +66,7 @@ export const contextReadCapability = {
     title: 'Read context you hold',
     descriptions: {
         sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
-        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list with scopeKind ["artifact"] shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
+        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list with scopeKind ["artifact"] shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all context types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
     },
     annotation: 'read-only',
     params: {
@@ -301,7 +302,7 @@ function presentOpenResult(result, env) {
             return [];
         const row = item;
         const ask = row.grantRequest;
-        if (row.status !== 'active' || ask?.primitive !== 'context' || ask.kind !== 'access-request' || ask.holderId !== fullCreds(env).agentId || !ask.scope?.id || !['artifact', 'chat', 'agreement', 'task'].includes(ask.scope.kind ?? ''))
+        if (row.status !== 'active' || !isContextAccessRequest(ask) || ask.holderId !== fullCreds(env).agentId || !ask.scope?.id || !['artifact', 'chat', 'agreement', 'task'].includes(ask.scope.kind ?? ''))
             return [];
         return [{ kind: 'resume', tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { [`${ask.scope.kind}Id`]: ask.scope.id }, effect: 'read_only', note: 'Approval recorded. Open the original scope; the server rechecks expiry and revocation.' }];
     });
@@ -406,30 +407,35 @@ export const accessRequestCapability = {
     key: 'access_request',
     names: { sdk: 'access_request', mcp: 'ziggs_access_request' },
     title: 'Request access for yourself',
+    annotation: 'write', needsAgentId: true,
     descriptions: {
-        sdk: 'Create a pending approval agreement for the calling agent to access one artifact, chat, agreement context, or task branch for 1–168 hours. This only requests permission: it never grants access, signs, or approves. After the authorized person approves, open the original resource. Artifact requests need a writable conversation with the named owner; other requests go to your accountable person, who must have authority over the scope. Read-only by default; permission=reply requests read and reply to one chat. No spending or work commitment. Reuse idempotencyKey for a retry.',
-        mcp: 'Ask for missing access through a pending approval agreement. Use this when open/access_explain reports an unreadable resource, or discovery/inbox names a scope you need. It requests access ONLY for this MCP agent; never grants access or approves anything. Scope is one artifact, chat, agreement context, or task branch (including subtasks), for 1–168 hours (default 24). Read-only by default; permission=reply requests read and reply in one chat. For earlier chat messages explicitly set temporal=from-start. Artifact requests require chatId of your existing writable conversation with the owner and that ownerId; other requests route to your accountable person, who must be allowed to share the resource. Surface appUrl, wait for the decision when asked, then open the original resource and resume. Pending grants no access. Never use issue_grant, change identity, or form a generic work agreement to recover missing access.',
+        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Artifact requests need chatId and ownerId of the person authorized to share it. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Artifact requests require chatId and ownerId of the authorized person in that conversation. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
     },
-    annotation: 'write', needsAgentId: true,
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
-        scopeId: { type: 'string', required: true, description: 'Original returned resource id; this request does not open a new resource' },
+        scopeId: { type: 'string', description: 'Original resource id. Omit when using a hire agreementId to request its workspace summary.' },
+        agreementId: { type: 'string', description: 'Artifact scope only: current hire id, used instead of scopeId to request the system-maintained workspace summary.' },
         reason: { type: 'string', required: true, description: 'Why access is needed and who will receive the reply or summary' },
         permission: { type: 'string', enum: ['read', 'reply'], description: 'read by default; reply is read and reply and is only valid for a chat' },
         temporal: { type: 'string', enum: ['from-now', 'from-start'], description: 'Chat history requested; default from-now. Earlier messages need from-start. Other resources use from-start.' },
         durationHours: { type: 'number', description: 'Integer 1–168 hours after approval; default 24' },
-        chatId: { type: 'string', description: 'Artifact requests only: existing conversation with the owner' },
-        ownerId: { type: 'string', description: 'Artifact requests only: human account or participant reference in that conversation' },
+        chatId: { type: 'string', description: 'Artifact or workspace requests only: existing conversation with the owner' },
+        ownerId: { type: 'string', description: 'Artifact or workspace requests only: human account or participant reference in that conversation' },
         idempotencyKey: { type: 'string', description: 'Reuse for the same logical request' },
     },
     handler: async (args, env) => {
-        for (const key of ['scopeKind', 'scopeId', 'reason']) {
+        for (const key of ['scopeKind', 'reason']) {
             if (typeof args[key] !== 'string' || !String(args[key]).trim())
                 throw new Error(`${key} is required`);
         }
         const scopeKind = args.scopeKind;
         if (!['artifact', 'chat', 'agreement', 'task'].includes(scopeKind))
             throw new Error('Unsupported scopeKind');
+        const agreementId = typeof args.agreementId === 'string' ? args.agreementId.trim() : undefined;
+        const scopeId = typeof args.scopeId === 'string' ? args.scopeId.trim() : undefined;
+        if (Boolean(agreementId) === Boolean(scopeId) || (agreementId && scopeKind !== 'artifact'))
+            throw new Error('Provide scopeId, or agreementId for its workspace summary artifact');
         const permission = args.permission ?? 'read';
         if (!['read', 'reply'].includes(String(permission)) || (permission === 'reply' && scopeKind !== 'chat'))
             throw new Error('Only chat access may request reply permission');
@@ -440,15 +446,15 @@ export const accessRequestCapability = {
             throw new Error('durationHours must be an integer between 1 and 168');
         const creds = fullCreds(env);
         const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).requestAccess({
-            scopeKind, scopeId: String(args.scopeId).trim(), reason: String(args.reason).trim(),
+            scopeKind, scopeId, agreementId, reason: String(args.reason).trim(),
             permission: permission, temporal: args.temporal,
             durationHours, chatId: args.chatId, ownerId: args.ownerId,
         }, { idempotencyKey: args.idempotencyKey, laneId: creds.laneId });
         return {
             ...result, outcome: 'pending', state: 'requested', actingAgentId: creds.agentId,
-            scope: { kind: scopeKind, id: args.scopeId },
+            scope: result.scope ?? { kind: scopeKind, id: scopeId },
             appUrl: `${(env.webUrl ?? 'https://ziggsai.com').replace(/\/$/, '')}/app/agreements/${encodeURIComponent(result.agreementId)}`,
-            resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: { [`${scopeKind}Id`]: args.scopeId } },
+            resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } },
             note: 'No access granted. The authorized person must approve; then open the original resource using the same agent identity.',
         };
     },

package/dist/http/ContextGrantsClient.d.ts

@@ -99,7 +99,8 @@ export declare class ContextGrantsClient {
     /** Request-only endpoint: a successful call must still have granted no access. */
     requestAccess(input: {
         scopeKind: 'artifact' | 'chat' | 'agreement' | 'task';
-        scopeId: string;
+        scopeId?: string;
+        agreementId?: string;
         reason: string;
         permission?: 'read' | 'reply';
         temporal?: 'from-now' | 'from-start';
@@ -113,6 +114,10 @@ export declare class ContextGrantsClient {
         status: 'pending_approval';
         agreementId: string;
         accessGranted: false;
+        scope?: {
+            kind: string;
+            id: string;
+        };
     }>;
     requestArtifactAccess(artifactId: string, input: {
         chatId: string;

package/dist/http/ContextGrantsClient.js

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

package/dist/http/ContextReadClient.d.ts

@@ -117,7 +117,6 @@ export declare class ContextReadClient {
         contextGrantId?: string;
         agreementId?: string;
         taskId?: string;
-        messageId?: string;
         artifactId?: string;
         via?: string;
     }): Promise<ContextSnapshotResult>;

package/dist/http/ContextReadClient.js

@@ -124,8 +124,6 @@ export class ContextReadClient {
         url.searchParams.set('via', opts.taskId ? `task:${opts.taskId}` : opts.via ?? (chatId.startsWith('agrn-') ? `agreement:${opts.agreementId ?? chatId.slice(5)}` : `chat:${chatId}`));
         if (opts.agreementId)
             url.searchParams.set('agreementId', opts.agreementId);
-        if (opts.messageId)
-            url.searchParams.set('messageId', opts.messageId);
         if (opts.artifactId)
             url.searchParams.set('artifactId', opts.artifactId);
         if (opts.maxMessages != null) {

package/dist/http/ToolPickClient.d.ts

@@ -0,0 +1,25 @@
+import type { Creds } from '../types.js';
+/** One catalog row as the picker reads it. */
+export interface ToolPickOption {
+    name: string;
+    line: string;
+}
+/**
+ * - `pick`         one tool does the need: `tool` names it.
+ * - `nothing_fits` no tool does it.
+ * - `unsure` / `off` no answer worth giving: show the list.
+ */
+export interface ToolPickAnswer {
+    how: 'pick' | 'nothing_fits' | 'unsure' | 'off';
+    tool?: string;
+    confidence?: number;
+}
+/** Null means "no answer": the surface shows the list it always has. */
+export type PickTool = (need: string, options: ToolPickOption[]) => Promise<ToolPickAnswer | null>;
+/**
+ * The backend picker: `POST /internal/tool-pick` with this connection's key.
+ * The model call and its key live on the backend, since this server also runs
+ * on a caller's own machine. Any failure is null, including the 404 from a
+ * backend that predates the route.
+ */
+export declare function backendToolPick(creds: Creds): PickTool;

package/dist/http/ToolPickClient.js

@@ -0,0 +1,35 @@
+import { buildCredsHeaders } from './operatorHeaders.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+/** A listing is always the fallback, so waiting long for a pick buys nothing. */
+const TIMEOUT_MS = 6000;
+/**
+ * The backend picker: `POST /internal/tool-pick` with this connection's key.
+ * The model call and its key live on the backend, since this server also runs
+ * on a caller's own machine. Any failure is null, including the 404 from a
+ * backend that predates the route.
+ */
+export function backendToolPick(creds) {
+    return async (need, options) => {
+        if (!creds.operatorKey)
+            return null;
+        try {
+            const res = await fetch(`${getBackendUrl()}/internal/tool-pick`, {
+                method: 'POST',
+                headers: buildCredsHeaders(creds),
+                body: JSON.stringify({ need, options }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => undefined);
+                return null;
+            }
+            const data = (await res.json().catch(() => null));
+            if (!data || typeof data.how !== 'string')
+                return null;
+            return data;
+        }
+        catch {
+            return null;
+        }
+    };
+}

package/dist/http/index.d.ts

@@ -33,3 +33,4 @@ export { InboxClient } from './InboxClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from '../inboxAck.js';
 export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { backendToolPick, type ToolPickOption, type ToolPickAnswer, type PickTool } from './ToolPickClient.js';

package/dist/http/index.js

@@ -25,3 +25,4 @@ export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds,
 // because the MCP transports in agent-sdk and ziggs-mcp send it too, and a
 // copy of a header nobody notices missing goes stale unseen.
 export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { backendToolPick } from './ToolPickClient.js';

package/dist/index.d.ts

@@ -24,3 +24,4 @@ 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';
+export { isContextAccessRequest } from './shared/contextAccessRequest.js';

package/dist/index.js

@@ -23,3 +23,4 @@ export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdenti
 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';
+export { isContextAccessRequest } from './shared/contextAccessRequest.js';

package/dist/shared/contextAccessRequest.d.ts

@@ -0,0 +1,12 @@
+/** The common marker carried by access-request approvals and notifications. */
+export interface ContextAccessRequest {
+    primitive: 'context';
+    kind: 'access-request';
+    holderId?: string;
+    scope?: {
+        kind?: string;
+        id?: string;
+    };
+    resumeAgreementId?: string;
+}
+export declare function isContextAccessRequest(value: unknown): value is ContextAccessRequest;

package/dist/shared/contextAccessRequest.js

@@ -0,0 +1,6 @@
+export function isContextAccessRequest(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return row.primitive === 'context' && row.kind === 'access-request';
+}

package/package.json

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