@ziggs-ai/api-client 0.37.7 → 0.37.9

package/dist/capabilities/chatListFields.d.ts

@@ -6,7 +6,7 @@
  * 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"];
+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;

package/dist/capabilities/chatListFields.js

@@ -14,6 +14,9 @@ export const CHAT_LIST_DEFAULT_FIELDS = [
     'lastMessage',
     'unreadCount',
     'participantSummary',
+    // A room you may only list says so, with the read request ready to file.
+    'readable',
+    'requestAccess',
 ];
 function slimParticipant(row) {
     if (!row || typeof row !== 'object' || Array.isArray(row))

package/dist/capabilities/context.js

@@ -425,14 +425,14 @@ export const accessRequestCapability = {
     title: 'Request access for yourself or named readers',
     annotation: 'destructive', needsAgentId: true,
     descriptions: {
-        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. 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. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by id or the participant reference this room shows you); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. 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. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by id or the participant reference this room shows you); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. To see which rooms a person is in (to find the room they mean), request scopeKind=person, scopeId=their person id, permission=list, from that person; once they approve, your chat list shows their rooms, each marked readable or not, and reading one still needs its own request. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
     },
     params: {
-        scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
+        scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task', 'person'] },
         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', 'work'], description: 'read by default; reply is read and reply and is only valid for a chat; work lets you create work under an agreement you can read but not work on, and lasts until it ends' },
+        permission: { type: 'string', enum: ['read', 'reply', 'work', 'list'], description: 'read by default; reply is read and reply and is only valid for a chat; work lets you create work under an agreement you can read but not work on, and lasts until it ends; list is required for a person scope and shows which rooms they are in, never their messages' },
         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 or workspace requests only: existing conversation with the owner' },
@@ -462,14 +462,16 @@ export const accessRequestCapability = {
                 throw new Error(`${key} is required`);
         }
         const scopeKind = args.scopeKind;
-        if (!['artifact', 'chat', 'agreement', 'task'].includes(scopeKind))
+        if (!['artifact', 'chat', 'agreement', 'task', 'person'].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', 'work'].includes(String(permission)) || (permission === 'reply' && scopeKind !== 'chat'))
+        const permission = args.permission ?? (scopeKind === 'person' ? 'list' : 'read');
+        if ((permission === 'list') !== (scopeKind === 'person'))
+            throw new Error('A person scope is requested with permission=list, and list only for a person');
+        if (!['read', 'reply', 'work', 'list'].includes(String(permission)) || (permission === 'reply' && scopeKind !== 'chat'))
             throw new Error('Only chat access may request reply permission');
         if (permission === 'work' && scopeKind !== 'agreement')
             throw new Error('Only agreement access may request work permission');
@@ -503,7 +505,10 @@ export const accessRequestCapability = {
             ...(actingAgentId ? { actingAgentId } : {}),
             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: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } },
+            // A person scope opens nothing: the yes shows up in the chat list.
+            ...(scopeKind === 'person'
+                ? env.surface === 'mcp' ? { resumeAfterApproval: { tool: 'ziggs_chat_list', args: {} } } : {}
+                : { resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } } }),
             note: `${result.message ?? 'A request card is open.'} No access granted until they approve; then open the original resource using the same agent identity.`,
         };
     },

package/dist/capabilities/mcpBriefs.js

@@ -100,7 +100,7 @@ const BRIEFS = {
     },
     // Rooms
     ziggs_chat_list: {
-        does: 'Lists rooms you hold a grant on, with last message and unread count. fields adds members or rosterSummary.',
+        does: 'Lists rooms you hold a grant on, with last message and unread count, plus the rooms a person let you list, marked readable: false with no message and the read request to file. fields adds members or rosterSummary.',
     },
     ziggs_chat_open: {
         does: 'Opens or reuses a conversation with a person or agent (participantId), starts a group (participantIds), or invites people into a room (chatId).',
@@ -178,7 +178,7 @@ const BRIEFS = {
     },
     // Tasks
     ziggs_task_create: {
-        does: 'Creates a task under an active agreement, or a work graph under a root task. plan sets its checklist.',
+        does: 'Creates a task under an active agreement, or a job with its children in one call. plan sets its checklist.',
         changes: 'creates the tasks and notifies their assignees',
     },
     ziggs_task_get: {
@@ -200,7 +200,7 @@ const BRIEFS = {
         changes: 'closes the task, proving nobody read or paid; the same idempotencyKey is a no-op',
     },
     ziggs_task_cancel: {
-        does: 'Cancels one task. Cancelling a held graph’s root withdraws the graph.',
+        does: 'Cancels one task. Cancelling a job cancels its live children.',
         changes: 'the task is cancelled',
     },
     ziggs_task_acknowledge_control: {

package/dist/capabilities/tasks.js

@@ -72,14 +72,14 @@ export const cancelTaskCapability = {
     names: { sdk: 'task_cancel', mcp: 'ziggs_task_cancel' },
     title: 'Cancel a task',
     descriptions: {
-        sdk: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
+        sdk: 'Cancel one task (PATCH /tasks/:id/cancel). Cancelling a job cancels its live children — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
     },
     annotation: 'destructive',
     params: {
         taskId: {
             type: 'string',
             required: true,
-            description: 'The task to cancel. For a held graph, pass the root.',
+            description: 'The task to cancel. To withdraw a whole job, pass the job.',
         },
     },
     needsAgentId: true,

package/dist/http/ChatClient.d.ts

@@ -153,7 +153,10 @@ export declare function addChatMember(input: AddChatMemberInput, creds: Creds):
  * an existing participant and `chatId` is omitted.
  */
 export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
-export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;
+export declare function listMyChats(creds: Creds, filters?: {
+    participantId?: string;
+    readable?: boolean;
+}): Promise<ChatSummary[]>;
 export declare class ChatClient {
     private creds;
     /**

package/dist/http/ChatClient.js

@@ -154,14 +154,20 @@ export async function sendChatMessage(input, creds) {
         ...(coverage ? { coverage } : {}),
     };
 }
-export async function listMyChats(creds) {
+export async function listMyChats(creds, filters = {}) {
     assertCreds(creds, 'list my chats');
+    const query = new URLSearchParams();
+    if (filters.participantId)
+        query.set('participantId', filters.participantId);
+    if (filters.readable !== undefined)
+        query.set('readable', String(filters.readable));
+    const qs = query.toString();
     // empty array only for a genuine empty 200; any failure (non-2xx /
     // network) throws so ziggs_chat_list reports a real error instead of "you
     // have no chats". HTTP failures are ApiError (status/body/code).
     let res;
     try {
-        res = await fetch(`${getBackendUrl()}/chats/mine`, {
+        res = await fetch(`${getBackendUrl()}/chats/mine${qs ? `?${qs}` : ''}`, {
             method: 'GET',
             headers: buildHeaders(creds),
         });

package/dist/http/ContextGrantsClient.d.ts

@@ -98,11 +98,11 @@ export declare class ContextGrantsClient {
     issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
     /** Request-only endpoint: a successful call must still have granted no access. */
     requestAccess(input: {
-        scopeKind: 'artifact' | 'chat' | 'agreement' | 'task';
+        scopeKind: 'artifact' | 'chat' | 'agreement' | 'task' | 'person';
         scopeId?: string;
         agreementId?: string;
         reason: string;
-        permission?: 'read' | 'reply' | 'work';
+        permission?: 'read' | 'reply' | 'work' | 'list';
         temporal?: 'from-now' | 'from-start';
         durationHours?: number;
         chatId?: string;

package/dist/http/TaskClient.d.ts

@@ -41,21 +41,28 @@ export declare function acknowledgeTaskControl(taskId: string, requestId: string
  * subcontract inputs rather than teaching those routes to keep one.
  */
 export type PlanReviewTiming = 'with_proposal' | 'before_execution';
-export interface CreateTaskGraphNodeData {
-    nodeId: string;
+/**
+ * One child created with its parent, all or none. `name` only lets siblings
+ * name each other in `waitsOn`; it is not stored, and the create answers with
+ * the task id each name became.
+ */
+export interface CreateTaskChildData {
+    name: string;
     agreementId: string;
     description: string;
     title?: string;
     assigneeId?: string;
+    /** Names of sibling children in the same create that must finish first. */
     waitsOn?: string[];
     joinKind?: 'all' | 'any';
-    /** A yes/no question over the steps this one waits on; it runs only on yes. */
+    /** A yes/no question over the children this one waits on; it runs only on yes. */
     runIf?: string;
-}
-export interface CreateTaskGraphData {
-    nodes: CreateTaskGraphNodeData[];
     inputArtifactIds?: string[];
-    review?: 'before_execution';
+}
+/** What a create with children answers for each one. */
+export interface CreatedTaskChild {
+    name: string;
+    taskId: string;
 }
 export interface CreateTaskData {
     description: string;
@@ -89,8 +96,20 @@ export interface CreateTaskData {
      * the shape in its own control flow where nothing else can see it.
      */
     waitsOn?: string[];
-    /** Atomically declare a native work graph beneath the returned root task. */
-    graph?: CreateTaskGraphData;
+    /**
+     * How the task closes, fixed at create. `children` (the default when
+     * `children` is given) makes it a job that closes when its children close:
+     * completed when every child no sibling waits on completed or was skipped.
+     * `result` (the default otherwise) closes by its own result.
+     */
+    closesBy?: 'result' | 'children';
+    /**
+     * Children created with this task in one call, all or none. The job's
+     * `inputArtifactIds` go to the children that wait on nothing, and
+     * `planReviewTiming: before_execution` holds every child until this task's
+     * plan is acknowledged.
+     */
+    children?: CreateTaskChildData[];
     /**
      * When the answer stops being useful, ISO 8601. At the deadline
      * the holder posts what it has and where it is stuck, and stops. A deadline
@@ -115,7 +134,9 @@ export interface CreateTaskCheckBackData {
     /** Total reminders allowed per person asked, after the first ask. */
     maxReminders: number;
 }
-export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
+export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task & {
+    children?: CreatedTaskChild[];
+}>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
 export interface UpdateTaskStateData {
     result?: unknown;
@@ -212,7 +233,9 @@ export declare class TaskClient {
     constructor(operatorKey: string, agentId?: string);
     requestControl(taskId: string, request: Parameters<typeof requestTaskControl>[1]): Promise<TaskWriteConfirm>;
     acknowledgeControl(taskId: string, requestId: string, supported?: boolean): Promise<TaskWriteConfirm>;
-    createTask(data: CreateTaskData): Promise<Task>;
+    createTask(data: CreateTaskData): Promise<Task & {
+        children?: CreatedTaskChild[];
+    }>;
     getTask(taskId: string): Promise<Task>;
     updateTaskState(taskId: string, state: TaskState, data?: UpdateTaskStateData): Promise<TaskWriteConfirm>;
     getActiveTasksForAgent(agentId: string): Promise<Task[]>;

package/dist/http/TaskClient.js

@@ -112,7 +112,10 @@ export async function createTask(taskData, creds) {
     const task = extractTask(data);
     if (!task)
         throw new Error('Invalid response: task data not found');
-    return task;
+    const children = data?.children;
+    return Array.isArray(children)
+        ? { ...task, children: children }
+        : task;
 }
 export async function getTask(taskId, creds) {
     if (!taskId)

package/dist/types.d.ts

@@ -103,17 +103,16 @@ export interface Task {
      */
     heldByDeps?: boolean;
     joinKind?: 'all' | 'any';
-    graph?: {
-        nodes: Array<{
-            nodeId: string;
-            taskId: string;
-        }>;
-        review?: 'before_execution';
-    } | null;
-    graphNodeId?: string | null;
-    heldByGraphReview?: boolean;
     /**
-     * A graph step that runs only if a yes/no question holds over the steps it
+     * How the task closes, fixed at create. `children` makes it a job: never
+     * handed out, it closes when its children (the tasks naming it as their
+     * parent) close.
+     */
+    closesBy?: 'result' | 'children';
+    /** True while the task waits for its parent's plan to be acknowledged. */
+    heldByParentReview?: boolean;
+    /**
+     * A child that runs only if a yes/no question holds over the steps it
      * waits on. Once asked: `run`, `skipped` (closed cancelled without running),
      * `held` (waiting for the buyer to acknowledge its plan) or `buyer_run`.
      */

package/package.json

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