@ziggs-ai/api-client 0.37.5 → 0.37.7

package/dist/capabilities/agreementVerbs.js

@@ -1,3 +1,4 @@
+import { SOURCES_PARAM, sourcesArg } from './sources.js';
 import { delegateAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from '../http/AgreementClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
@@ -56,6 +57,7 @@ const TERMS_PARAMS = {
         type: 'number',
         description: 'End the engagement after this many tasks.',
     },
+    sources: SOURCES_PARAM,
 };
 /** Pull the shared terms off a validated arg bag. */
 function termsFrom(args) {
@@ -77,6 +79,7 @@ function termsFrom(args) {
         ...(args['maxExecutions'] === undefined
             ? {}
             : { maxExecutions: args['maxExecutions'] }),
+        ...sourcesArg(args),
     };
 }
 function engagementKindFrom(args) {

package/dist/capabilities/agreements.js

@@ -110,11 +110,16 @@ export const agreementClaimCapability = {
             type: 'object',
             description: 'Only when the listing\'s requiredConnections name a kind (e.g. ledger, customer): one of YOUR connections for each, as { "<kind>": "<connectionId>" }. The hire is granted exactly that connection and the grant ends with it. Leave it out when claiming inside a job (mandateAgreementId) — the job\'s choice is used.',
         },
+        hireFor: {
+            type: 'string',
+            enum: ['me', 'workspace'],
+            description: 'Only when hiring an agent\'s listing: who the hire is for. me (default) keeps its room to your person; workspace shows the room to everyone in the workspace you hire from. Ask your person when it is not clear.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}), ...(claimConnections(args['connections']) ?? {}) });
+        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}), ...(claimConnections(args['connections']) ?? {}), ...(args['hireFor'] === 'workspace' ? { hireFor: 'workspace' } : {}) });
         return presentClaimResult(agreement, kind, env, room);
     },
 };

package/dist/capabilities/artifacts.js

@@ -1,3 +1,4 @@
+import { SOURCES_PARAM, sourcesArg } from './sources.js';
 import { ARTIFACT_FILE_FORMATS, ArtifactsClient, } from '../http/ArtifactsClient.js';
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient, } from '../http/ContextDiscoveryClient.js';
@@ -218,6 +219,7 @@ export const recordArtifactCapability = {
                 'text is the in-Ziggs summary. Ziggs stores the link and does not fetch it. ' +
                 'A grant on this artifact does not open the other system.',
         },
+        sources: SOURCES_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -265,6 +267,7 @@ export const recordArtifactCapability = {
             contentType,
             idempotencyKey: args['idempotencyKey'],
             ...(externalRef ? { externalRef } : {}),
+            ...sourcesArg(args),
         });
         return {
             ok: true,

package/dist/capabilities/index.d.ts

@@ -1,4 +1,5 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
+export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, type WriteSource, type WriteSourceKind, } from './sources.js';
 export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';

package/dist/capabilities/index.js

@@ -1,4 +1,5 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
+export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, } from './sources.js';
 export { hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';

package/dist/capabilities/introductions.js

@@ -1,3 +1,4 @@
+import { SOURCES_PARAM, sourcesArg } from './sources.js';
 import { IntroductionsClient } from '../http/IntroductionsClient.js';
 import { nextCall } from './nextCall.js';
 import { fullCreds } from './types.js';
@@ -34,6 +35,7 @@ export const mintIntroductionCapability = {
             type: 'string',
             description: 'One line for the other side to read when they open it — why you want to connect.',
         },
+        sources: SOURCES_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -43,6 +45,7 @@ export const mintIntroductionCapability = {
             ...(args['venue'] ? { venue: args['venue'] } : {}),
             ...(args['venueRef'] ? { venueRef: args['venueRef'] } : {}),
             ...(args['note'] ? { note: args['note'] } : {}),
+            ...sourcesArg(args),
         });
         return {
             introduction: intro,

package/dist/capabilities/sources.d.ts

@@ -0,0 +1,29 @@
+import type { CapabilityParam } from './types.js';
+/**
+ * What a write drew on. Every write that carries text the agent composed
+ * can say it: things in Ziggs by kind and id, or outside things as a url.
+ * Never shown to anyone; the writer's company admin reads it back by query.
+ */
+export declare const WRITE_SOURCE_KINDS: readonly ["message", "artifact", "task_result", "task_plan_step", "url"];
+export type WriteSourceKind = (typeof WRITE_SOURCE_KINDS)[number];
+/**
+ * - `message`: `id` is the messageId, `chatId` its room.
+ * - `artifact`: `id` is the artifactId.
+ * - `task_result`: `id` is the taskId.
+ * - `task_plan_step`: `id` is the stepId, `taskId` its task.
+ * - `url`: `value` is the outside source.
+ */
+export interface WriteSource {
+    kind: WriteSourceKind;
+    id?: string;
+    chatId?: string;
+    taskId?: string;
+    value?: string;
+}
+/** One line, shared by every tool that takes `sources`: it is repeated per tool. */
+export declare const SOURCES_DESCRIPTION = "What this text drew on: {kind,id} for a message (+chatId), artifact, task_result or task_plan_step (+taskId); {kind:\"url\",value} outside. [] = nothing more.";
+export declare const SOURCES_PARAM: CapabilityParam;
+/** The `sources` a tool call carried, ready for the request body. */
+export declare function sourcesArg(args: Record<string, unknown>): {
+    sources: WriteSource[];
+} | Record<string, never>;

package/dist/capabilities/sources.js

@@ -0,0 +1,34 @@
+/**
+ * What a write drew on. Every write that carries text the agent composed
+ * can say it: things in Ziggs by kind and id, or outside things as a url.
+ * Never shown to anyone; the writer's company admin reads it back by query.
+ */
+export const WRITE_SOURCE_KINDS = [
+    'message',
+    'artifact',
+    'task_result',
+    'task_plan_step',
+    'url',
+];
+/** One line, shared by every tool that takes `sources`: it is repeated per tool. */
+export const SOURCES_DESCRIPTION = 'What this text drew on: {kind,id} for a message (+chatId), artifact, task_result or task_plan_step (+taskId); {kind:"url",value} outside. [] = nothing more.';
+export const SOURCES_PARAM = {
+    type: 'array',
+    description: SOURCES_DESCRIPTION,
+    items: {
+        type: 'object',
+        properties: {
+            kind: { type: 'string', enum: WRITE_SOURCE_KINDS },
+            id: { type: 'string' },
+            chatId: { type: 'string' },
+            taskId: { type: 'string' },
+            value: { type: 'string' },
+        },
+        required: ['kind'],
+    },
+};
+/** The `sources` a tool call carried, ready for the request body. */
+export function sourcesArg(args) {
+    const raw = args['sources'];
+    return Array.isArray(raw) ? { sources: raw } : {};
+}

package/dist/http/AgreementClient.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '../capabilities/sources.js';
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
@@ -8,6 +9,8 @@ import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience
  */
 export interface ProposeTerms {
     description: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
     price?: number;
     lifecycle?: string;
     expiresAt?: string;
@@ -125,6 +128,8 @@ export declare function proposeDirectTo(input: ProposeDirectInput, creds: Creds)
 export declare function proposeBroadcast(input: ProposeBroadcastInput, creds: Creds): Promise<Agreement>;
 export interface DelegateAgreementData {
     description: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
     executorId: string;
     /** Omit it and the server uses the parent agreement's own chat. */
     chatId?: string;
@@ -208,6 +213,8 @@ export interface CounterAgreementData {
     conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     description?: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 export declare function counterAgreement(agreementId: string, counter: CounterAgreementData, creds: Creds): Promise<Agreement>;
 export declare function getAgreementStatus(agreementId: string, creds: Creds): Promise<unknown | null>;
@@ -331,6 +338,12 @@ export interface ClaimOptions {
      * takes the job's and names none.
      */
     connections?: Record<string, string>;
+    /**
+     * Who a hire of a listing is for. `me` (the default) keeps its room to the
+     * person; `workspace` makes the workspace the payer and shows the room to
+     * every member.
+     */
+    hireFor?: 'me' | 'workspace';
 }
 /**
  * Where a hire made in a room stands on getting its agent in.

package/dist/http/AgreementClient.js

@@ -554,7 +554,7 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
     const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, {
         method: 'POST',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.chatId ? { chatId: opts.chatId } : {}), ...(opts.connections && Object.keys(opts.connections).length ? { connections: opts.connections } : {}) }),
+        body: JSON.stringify({ ...(opts.mandateAgreementId ? { mandateAgreementId: opts.mandateAgreementId } : {}), ...(opts.parentAgreementId ? { parentAgreementId: opts.parentAgreementId } : {}), ...(opts.chatId ? { chatId: opts.chatId } : {}), ...(opts.connections && Object.keys(opts.connections).length ? { connections: opts.connections } : {}), ...(opts.hireFor === 'workspace' ? { hireFor: 'workspace' } : {}) }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

package/dist/http/ArtifactsClient.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '../capabilities/sources.js';
 import type { ListReachableArtifactsResult } from '@ziggs-ai/contracts';
 /**
  * Inline `POST /artifacts` body cap (matches backend
@@ -91,6 +92,8 @@ export interface WriteArtifactInput {
      * The `text` is the in-Ziggs summary. Ziggs does not fetch the URL.
      */
     externalRef?: ArtifactExternalRef;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 /** Every file format the server stores — the contracts list, re-exported under the names callers already use. */
 export { ARTIFACT_FILE_FORMATS, type ArtifactExternalRef, type ArtifactFileFormat } from '@ziggs-ai/contracts';

package/dist/http/ArtifactsClient.js

@@ -194,6 +194,7 @@ export class ArtifactsClient {
                 ...(input.externalRef
                     ? { externalRef: input.externalRef }
                     : {}),
+                ...(input.sources ? { sources: input.sources } : {}),
             }),
         });
         const body = await res.text().catch(() => '');

package/dist/http/ChatClient.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '../capabilities/sources.js';
 import type { ChatReadDto } from '@ziggs-ai/contracts';
 import type { MessageDelivery as WireMessageDelivery, SendChatMessageResult as WireSendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
@@ -69,6 +70,8 @@ export interface SendChatMessageInput {
     /** Governing service agreement; independent of representation. */
     conversationAgreementId?: string;
     taskId?: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 /**
  * Where the server says a send landed.

package/dist/http/ChatClient.js

@@ -130,6 +130,7 @@ export async function sendChatMessage(input, creds) {
             underAgreementId: input.underAgreementId,
             conversationAgreementId: input.conversationAgreementId,
             taskId: input.taskId,
+            ...(input.sources ? { sources: input.sources } : {}),
         }),
     });
     if (!res.ok) {

package/dist/http/IntroductionsClient.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '../capabilities/sources.js';
 /** What became of one hello. `expired` is derived by the server, not stored. */
 export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' | 'expired';
 export type IntroductionOutcome = 'link_pending' | 'already_teammates' | 'already_linked';
@@ -56,6 +57,8 @@ export interface MintIntroductionInput {
     venue?: string;
     venueRef?: string;
     note?: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 /**
  * Introduction tokens — the one object to exchange when you meet an

package/dist/http/MarketplaceClient.d.ts

@@ -1,6 +1,9 @@
+import type { WriteSource } from '../capabilities/sources.js';
 import { type Creds, type Agreement, type BroadcastAudience } from '../types.js';
 export interface PublishOfferPayload {
     description: string;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
     price?: number;
     lifecycle?: string;
     expiresAt?: string;

package/dist/http/TaskClient.d.ts

@@ -1,3 +1,4 @@
+import type { WriteSource } from '../capabilities/sources.js';
 import { type Creds, type Task, type TaskState } from '../types.js';
 /**
  * Thin confirmation from task write verbs. Full object stays on
@@ -104,6 +105,8 @@ export interface CreateTaskData {
      * the whole object for a task nobody needs reminding about.
      */
     checkBack?: CreateTaskCheckBackData;
+    /** What the title and description drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 /** See {@link CreateTaskData.checkBack}. */
 export interface CreateTaskCheckBackData {
@@ -125,6 +128,8 @@ export interface UpdateTaskStateData {
      * stateless crash-replay reproduces it.
      */
     idempotencyKey?: string;
+    /** What the result drew on. Recorded only when a result is written. */
+    sources?: WriteSource[];
 }
 export declare function updateTaskState(taskId: string, state: TaskState, data: UpdateTaskStateData | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function getActiveTasksForAgent(agentId: string, creds: Creds): Promise<Task[]>;
@@ -145,6 +150,8 @@ export interface PlanReplaceStep {
     status?: 'pending' | 'in_progress' | 'completed' | 'skipped';
     /** Optional step output stored with this replace. */
     result?: unknown;
+    /** What this text drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 }
 export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<TaskWriteConfirm>;
 /** Named-step progress — only the listed steps change. */
@@ -152,6 +159,8 @@ export type PlanStepPatch = {
     stepId: string;
     status: 'pending' | 'in_progress' | 'completed' | 'skipped';
     result?: unknown;
+    /** What this step drew on. See {@link WriteSource}. */
+    sources?: WriteSource[];
 };
 /**
  * Who the holder is waiting on, because its last act was asking them.
@@ -166,7 +175,7 @@ export type TaskWaitingOn = {
     id: string;
 };
 export declare function updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[], creds: Creds, waitingOn?: TaskWaitingOn | null): Promise<TaskWriteConfirm>;
-export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds, waitingOn?: TaskWaitingOn | null): Promise<TaskWriteConfirm>;
+export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds, waitingOn?: TaskWaitingOn | null, sources?: WriteSource[]): Promise<TaskWriteConfirm>;
 export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<TaskWriteConfirm>;
 export interface ListTasksOptions {

package/dist/http/TaskClient.js

@@ -335,7 +335,7 @@ export async function updateTaskPlanSteps(taskId, patches, creds, waitingOn) {
         throw new Error('Invalid response: task write confirm not found');
     return confirm;
 }
-export async function updateTaskPlanStep(taskId, stepId, status, result, creds, waitingOn) {
+export async function updateTaskPlanStep(taskId, stepId, status, result, creds, waitingOn, sources) {
     if (!taskId)
         throw new Error('updateTaskPlanStep: taskId is required');
     if (!stepId)
@@ -354,6 +354,7 @@ export async function updateTaskPlanStep(taskId, stepId, status, result, creds,
             status,
             ...(result !== undefined && { result }),
             ...(waitingOn !== undefined ? { waitingOn } : {}),
+            ...(sources ? { sources } : {}),
         }),
     });
     if (!res.ok) {

package/package.json

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