@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/dist/server/ziggspay/ZiggsPayClient.js

@@ -0,0 +1,203 @@
+import 'dotenv/config';
+function getDefaultBaseUrl() {
+    return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+function randomIdempotencyKey(prefix = 'op') {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function parseError(text, fallback) {
+    if (!text)
+        return fallback;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed['error'] || parsed['message'] || text;
+    }
+    catch {
+        return text;
+    }
+}
+export class ZiggsPayClient {
+    operatorKey;
+    actAsAgentId;
+    baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }) {
+        if (!operatorKey || typeof operatorKey !== 'string')
+            throw new Error('ZiggsPayClient requires an operatorKey');
+        this.operatorKey = operatorKey;
+        this.actAsAgentId = actAsAgentId || null;
+        this.baseUrl = baseUrl || getDefaultBaseUrl();
+    }
+    async balance() {
+        const w = await this._get('/payments/wallet');
+        const wallet = w['wallet'];
+        return { walletId: wallet?.['walletId'] || null, currency: wallet?.['currency'] || 'pez', balance: w['balance'] ?? 0, availableBalance: w['availableBalance'] ?? 0 };
+    }
+    async resolve({ userId, agentId } = {}) {
+        if (!userId && !agentId)
+            throw new Error('resolve: provide userId or agentId');
+        const params = new URLSearchParams();
+        if (userId)
+            params.set('userId', userId);
+        if (agentId)
+            params.set('agentId', agentId);
+        const res = await this._get(`/payments/wallets/resolve?${params}`);
+        return res['wallet'] || null;
+    }
+    async transfer({ to, amount, idempotencyKey, description, paymentGrantId }) {
+        if (!to)
+            throw new Error('transfer: `to` is required');
+        if (!(Number.isInteger(amount) && amount > 0))
+            throw new Error('transfer: `amount` must be a positive integer (cents)');
+        if (this.actAsAgentId && !paymentGrantId)
+            throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
+        let toWalletId = to;
+        if (!to.startsWith('wal_')) {
+            const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
+            if (!w?.['walletId'])
+                throw new Error(`transfer: could not resolve wallet for "${to}"`);
+            toWalletId = w['walletId'];
+        }
+        const result = await this._post('/payments/transfer', { toWalletId, amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('xfer'), description, paymentGrantId });
+        if (result?.['status'] === 'approval_required') {
+            const approval = result['approval'] || {};
+            return { status: 'approval_required', approvalId: approval['approvalId'] || null, expiresAt: approval['expiresAt'] || null, reason: approval['reason'] || 'Amount exceeds auto-approve threshold', toWalletId, amount };
+        }
+        const tx = result?.['transaction'];
+        return { status: 'transferred', transactionId: tx?.['transactionId'] || null, toWalletId, amount };
+    }
+    async hold({ amount, idempotencyKey, description }) {
+        if (!(Number.isInteger(amount) && amount > 0))
+            throw new Error('hold: `amount` must be a positive integer (cents)');
+        return this._post('/payments/hold', { amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'), description });
+    }
+    async release({ holdId, action = 'complete', toWalletId, idempotencyKey }) {
+        return this._post(`/payments/release/${holdId}`, { idempotencyKey: idempotencyKey || randomIdempotencyKey('rel'), action, toWalletId });
+    }
+    async history(params = {}) {
+        const q = new URLSearchParams();
+        if (params.limit != null)
+            q.set('limit', String(params.limit));
+        if (params.offset != null)
+            q.set('offset', String(params.offset));
+        if (params.type)
+            q.set('type', params.type);
+        return this._get('/payments/history' + (q.toString() ? `?${q}` : ''));
+    }
+    async issueGrant({ holderId, caveats }) {
+        return this._post('/payments/grants', { holderId, caveats });
+    }
+    async attenuateGrant({ grantId, holderId, caveats }) {
+        return this._post(`/payments/grants/${grantId}/attenuate`, { holderId, caveats });
+    }
+    async revokeGrant(grantId) {
+        return this._request('DELETE', `/payments/grants/${grantId}`, undefined);
+    }
+    async listGrants() {
+        // GET /payments/grants was retired (ZIG-648); wallet grants the acting agent
+        // holds are listed via the unified GET /grants. Follow the cursor so a holder
+        // with more than one page isn't truncated; live grants only.
+        const all = [];
+        let cursor;
+        for (let page = 0; page < 50; page++) {
+            const q = new URLSearchParams({ scopeKind: 'wallet', health: 'active' });
+            if (cursor)
+                q.set('cursor', cursor);
+            const res = (await this._get(`/grants?${q.toString()}`));
+            all.push(...(res['items'] || []));
+            const next = res['nextCursor'];
+            if (!next)
+                break;
+            cursor = next;
+        }
+        return all;
+    }
+    async createTopUpIntent({ amount, description, currency } = {}) {
+        return this._post('/payments/onramp/intent', { amount, description, currency });
+    }
+    async confirmMockIntent(intentId) {
+        return this._post(`/payments/onramp/mock-confirm/${intentId}`, {});
+    }
+    async faucet({ amount, description = 'Faucet', idempotencyKey } = {}) {
+        return this._post('/payments/wallet/fund', { amount, idempotencyKey: idempotencyKey || randomIdempotencyKey('faucet'), description });
+    }
+    async approvals({ status = 'pending' } = {}) {
+        const res = await this._get(`/payments/approvals?status=${encodeURIComponent(status)}`);
+        return res['approvals'] || [];
+    }
+    async getApproval(approvalId) {
+        if (!approvalId)
+            throw new Error('getApproval: approvalId is required');
+        try {
+            const res = await this._get(`/payments/approvals/${approvalId}`);
+            return res?.['approval'] || null;
+        }
+        catch (err) {
+            if (err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async decide(approvalId, decision, note = '') {
+        return this._post(`/payments/approvals/${approvalId}/decide`, { decision, note });
+    }
+    async waitForApproval(approvalId, opts = {}) {
+        const pollMs = Math.max(500, opts.pollMs ?? 3_000);
+        const timeoutMs = Math.max(pollMs, opts.timeoutMs ?? 120_000);
+        const signal = opts.signal;
+        const deadline = Date.now() + timeoutMs;
+        const sleep = (ms) => new Promise((resolve, reject) => {
+            const timer = setTimeout(resolve, ms);
+            if (signal) {
+                if (signal.aborted) {
+                    clearTimeout(timer);
+                    reject(new Error('aborted'));
+                    return;
+                }
+                signal.addEventListener('abort', () => { clearTimeout(timer); reject(new Error('aborted')); }, { once: true });
+            }
+        });
+        while (true) {
+            if (signal?.aborted)
+                throw new Error('aborted');
+            const approval = await this.getApproval(approvalId);
+            if (!approval)
+                return { status: 'gone' };
+            const s = approval['status'];
+            if (s === 'executed')
+                return { status: 'executed', approval, transactionId: approval['executedTransactionId'] || null };
+            if (s === 'rejected')
+                return { status: 'rejected', approval };
+            if (s === 'expired')
+                return { status: 'expired', approval };
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return { status: 'timeout', approval };
+            await sleep(Math.min(pollMs, remaining));
+        }
+    }
+    _buildHeaders(extra = {}) {
+        const h = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+        if (this.actAsAgentId)
+            h['X-Agent-Id'] = this.actAsAgentId;
+        return h;
+    }
+    async _request(method, path, body) {
+        const init = { method, headers: this._buildHeaders(body !== undefined ? { 'content-type': 'application/json' } : {}) };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const response = await fetch(`${this.baseUrl}${path}`, init);
+        const text = await response.text();
+        if (!response.ok) {
+            const err = new Error(parseError(text, `HTTP ${response.status}`));
+            err.status = response.status;
+            err.body = text;
+            throw err;
+        }
+        return text ? JSON.parse(text) : null;
+    }
+    _get(path) { return this._request('GET', path, undefined); }
+    _post(path, body) { return this._request('POST', path, body ?? {}); }
+}
+export function createZiggsPayClient(opts) {
+    return new ZiggsPayClient(opts);
+}

package/dist/shared/ids.d.ts

@@ -0,0 +1 @@
+export declare function generateId(): string;

package/dist/shared/ids.js

@@ -0,0 +1,3 @@
+export function generateId() {
+    return `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}

package/dist/shared/runtimeLog.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Process-wide log levels for agentplus runtimes. Default is `info` so FSM /
+ * socket chatter stays quiet unless operators opt in.
+ *
+ * Env (first match wins for the debug shortcut):
+ * - `DEBUG_AGENTPLUS=1` or `AGENTPLUS_DEBUG=1` → threshold `debug`
+ * - `LOG_LEVEL` or `AGENTPLUS_LOG_LEVEL` → `debug` | `info` | `warn` | `error` | `silent`
+ *   (`silent` keeps only `error` output)
+ */
+export type RuntimeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Test hook: re-read env after `process.env` mutations. */
+export declare function resetRuntimeLogLevelCache(): void;
+export declare const runtimeLog: {
+    debug(scope: string, msg: string, ...rest: unknown[]): void;
+    info(scope: string, msg: string, ...rest: unknown[]): void;
+    warn(scope: string, msg: string, ...rest: unknown[]): void;
+    error(scope: string, msg: string, ...rest: unknown[]): void;
+};

package/dist/shared/runtimeLog.js

@@ -0,0 +1,68 @@
+/**
+ * Process-wide log levels for agentplus runtimes. Default is `info` so FSM /
+ * socket chatter stays quiet unless operators opt in.
+ *
+ * Env (first match wins for the debug shortcut):
+ * - `DEBUG_AGENTPLUS=1` or `AGENTPLUS_DEBUG=1` → threshold `debug`
+ * - `LOG_LEVEL` or `AGENTPLUS_LOG_LEVEL` → `debug` | `info` | `warn` | `error` | `silent`
+ *   (`silent` keeps only `error` output)
+ */
+const SEVERITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function parseThreshold() {
+    if (process.env.DEBUG_AGENTPLUS === '1' || process.env.AGENTPLUS_DEBUG === '1') {
+        return SEVERITY.debug;
+    }
+    const raw = (process.env.LOG_LEVEL ||
+        process.env.AGENTPLUS_LOG_LEVEL ||
+        'info').toLowerCase();
+    if (raw === 'silent' || raw === 'none')
+        return SEVERITY.error;
+    if (raw === 'debug' || raw === 'trace')
+        return SEVERITY.debug;
+    if (raw === 'warn')
+        return SEVERITY.warn;
+    if (raw === 'error')
+        return SEVERITY.error;
+    return SEVERITY.info;
+}
+let cachedThreshold = null;
+function threshold() {
+    if (cachedThreshold === null)
+        cachedThreshold = parseThreshold();
+    return cachedThreshold;
+}
+/** Test hook: re-read env after `process.env` mutations. */
+export function resetRuntimeLogLevelCache() {
+    cachedThreshold = null;
+}
+function shouldEmit(level) {
+    return SEVERITY[level] >= threshold();
+}
+function fmt(scope, msg) {
+    return `[${scope}] ${msg}`;
+}
+export const runtimeLog = {
+    debug(scope, msg, ...rest) {
+        if (!shouldEmit('debug'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    info(scope, msg, ...rest) {
+        if (!shouldEmit('info'))
+            return;
+        console.log(fmt(scope, msg), ...rest);
+    },
+    warn(scope, msg, ...rest) {
+        if (!shouldEmit('warn'))
+            return;
+        console.warn(fmt(scope, msg), ...rest);
+    },
+    error(scope, msg, ...rest) {
+        console.error(fmt(scope, msg), ...rest);
+    },
+};

package/dist/shared/types.d.ts

@@ -0,0 +1,22 @@
+export declare const EntryTypes: {
+    readonly MESSAGE: "message";
+    readonly NOTIFICATION: "notification";
+    readonly ARTIFACT: "artifact";
+    readonly TASK_HISTORY: "task_history";
+};
+export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
+export declare const ContentTypes: {
+    readonly TEXT: "text";
+    readonly OPERATION: "operation";
+    readonly CONTEXT: "context";
+    readonly RESULT: "result";
+    readonly TASK_UPDATE: "task_update";
+    readonly THOUGHT: "thought";
+};
+export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
+export declare const ContextProperties: {
+    readonly HISTORY: "history";
+    readonly AGREEMENTS: "agreements";
+    readonly AGENTS: "agents";
+    readonly USERS: "users";
+};

package/dist/shared/types.js

@@ -0,0 +1,23 @@
+// Inlined from `@ziggs-ai/api-client` so the pure SDK doesn't depend on the
+// Ziggs HTTP client. Both client and server agree on these string constants
+// because the protocol is the same — they're just two views of one schema.
+export const EntryTypes = {
+    MESSAGE: 'message',
+    NOTIFICATION: 'notification',
+    ARTIFACT: 'artifact',
+    TASK_HISTORY: 'task_history',
+};
+export const ContentTypes = {
+    TEXT: 'text',
+    OPERATION: 'operation',
+    CONTEXT: 'context',
+    RESULT: 'result',
+    TASK_UPDATE: 'task_update',
+    THOUGHT: 'thought',
+};
+export const ContextProperties = {
+    HISTORY: 'history',
+    AGREEMENTS: 'agreements',
+    AGENTS: 'agents',
+    USERS: 'users',
+};

package/dist/tasks/protocolRegistry.d.ts

@@ -0,0 +1,16 @@
+export declare const PROTOCOL_TOOL_TO_OPERATION: Readonly<{
+    readonly agreement_propose: "agreement-propose";
+    readonly agreement_subcontract: "agreement-subcontract";
+    readonly agreement_respond: "agreement-respond";
+    readonly agreement_counter_proposal: "agreement-counter-proposal";
+    readonly agreement_check_proposal: "agreement-check-proposal";
+    readonly agreement_revoke: "agreement-revoke";
+    readonly task_spawn: "task-spawn";
+    readonly task_update: "task-update";
+    readonly task_update_plan_step: "task-update-plan-step";
+}>;
+export type ProtocolToolName = keyof typeof PROTOCOL_TOOL_TO_OPERATION;
+export type ProtocolOperation = (typeof PROTOCOL_TOOL_TO_OPERATION)[ProtocolToolName];
+export declare const PROTOCOL_TOOL_NAMES: readonly ProtocolToolName[];
+export declare function mapProtocolToolToOperation(toolName: string): ProtocolOperation | null;
+export declare function isProtocolToolName(toolName: string): toolName is ProtocolToolName;

package/dist/tasks/protocolRegistry.js

@@ -0,0 +1,20 @@
+export const PROTOCOL_TOOL_TO_OPERATION = Object.freeze({
+    agreement_propose: 'agreement-propose',
+    agreement_subcontract: 'agreement-subcontract',
+    agreement_respond: 'agreement-respond',
+    agreement_counter_proposal: 'agreement-counter-proposal',
+    agreement_check_proposal: 'agreement-check-proposal',
+    agreement_revoke: 'agreement-revoke',
+    task_spawn: 'task-spawn',
+    task_update: 'task-update',
+    task_update_plan_step: 'task-update-plan-step',
+});
+export const PROTOCOL_TOOL_NAMES = Object.freeze(Object.keys(PROTOCOL_TOOL_TO_OPERATION));
+export function mapProtocolToolToOperation(toolName) {
+    if (!toolName || typeof toolName !== 'string')
+        return null;
+    return PROTOCOL_TOOL_TO_OPERATION[toolName] ?? null;
+}
+export function isProtocolToolName(toolName) {
+    return mapProtocolToolToOperation(toolName) != null;
+}

package/dist/tools/ToolManager.d.ts

@@ -0,0 +1,12 @@
+import { ToolProvider } from './ToolProvider.js';
+import type { ToolDefinition } from './defineTool.js';
+export declare class ToolManager extends ToolProvider {
+    private tools;
+    constructor();
+    register(tool: ToolDefinition): string;
+    registerAll(tools?: ToolDefinition[]): void;
+    getAvailableTools(): Promise<ToolDefinition[]>;
+    getTool(name: string): ToolDefinition | null;
+    executeTool(name: string, args?: Record<string, unknown>, context?: Record<string, unknown>): Promise<unknown>;
+    private _validateArgs;
+}

package/dist/tools/ToolManager.js

@@ -0,0 +1,74 @@
+import AjvModule from 'ajv';
+import { ToolProvider } from './ToolProvider.js';
+const AjvClass = AjvModule.default ?? AjvModule;
+const ajv = new AjvClass({ allErrors: true, strict: false });
+function makeError(message, type, extra) {
+    const err = new Error(message);
+    err.type = type;
+    if (extra)
+        Object.assign(err, extra);
+    return err;
+}
+function stripNullish(args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return args;
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (v !== null && v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+export class ToolManager extends ToolProvider {
+    tools;
+    constructor() {
+        super();
+        this.tools = new Map();
+    }
+    register(tool) {
+        if (!tool?.schema)
+            throw makeError('Tool must have a schema', 'invalid_tool');
+        if (typeof tool.handler !== 'function')
+            throw makeError('Tool must have a handler function', 'invalid_tool');
+        const name = (tool.schema.function?.['name'] || tool.schema['name']);
+        if (!name)
+            throw makeError('Tool schema must have a name', 'invalid_tool');
+        this.tools.set(name, tool);
+        return name;
+    }
+    registerAll(tools = []) {
+        for (const tool of tools)
+            this.register(tool);
+    }
+    async getAvailableTools() {
+        return Array.from(this.tools.values());
+    }
+    getTool(name) {
+        const normalized = this._normalizeName(name);
+        return this.tools.get(normalized) ?? null;
+    }
+    async executeTool(name, args = {}, context = {}) {
+        const normalized = this._normalizeName(name);
+        const tool = this.tools.get(normalized);
+        if (!tool)
+            throw makeError(`Tool not found: ${name}`, 'tool_not_found');
+        const cleanedArgs = stripNullish(args);
+        this._validateArgs(tool, cleanedArgs);
+        try {
+            return await tool.handler(cleanedArgs, context);
+        }
+        catch (error) {
+            throw makeError(`Tool "${name}" failed: ${error.message}`, 'tool_error', { cause: error });
+        }
+    }
+    _validateArgs(tool, args) {
+        const parameters = tool.schema.function?.['parameters'] || tool.schema['parameters'];
+        if (!parameters)
+            return;
+        const validate = ajv.compile(parameters);
+        if (!validate(args)) {
+            const name = tool.schema.function?.['name'];
+            throw makeError(`Invalid args for "${name}": ${ajv.errorsText(validate.errors)}`, 'validation_error', { data: { errors: validate.errors } });
+        }
+    }
+}

package/dist/tools/ToolProvider.d.ts

@@ -0,0 +1,6 @@
+export declare class ToolProvider {
+    getAvailableTools(): Promise<unknown[]>;
+    executeTool(_name: string, _args?: Record<string, unknown>, _context?: Record<string, unknown>): Promise<unknown>;
+    getTool(_name: string): unknown | null;
+    _normalizeName(name: unknown): unknown;
+}

package/dist/tools/ToolProvider.js

@@ -0,0 +1,21 @@
+export class ToolProvider {
+    async getAvailableTools() {
+        throw new Error('getAvailableTools must be implemented');
+    }
+    async executeTool(_name, _args, _context) {
+        throw new Error('executeTool must be implemented');
+    }
+    getTool(_name) {
+        throw new Error('getTool must be implemented');
+    }
+    _normalizeName(name) {
+        if (!name || typeof name !== 'string')
+            return name;
+        const prefixes = ['functions.', 'tools.', 'function.', 'tool.'];
+        for (const prefix of prefixes) {
+            if (name.startsWith(prefix))
+                return name.substring(prefix.length);
+        }
+        return name;
+    }
+}

package/dist/tools/defineTool.d.ts

@@ -0,0 +1,27 @@
+export interface ToolDefinition {
+    schema: {
+        type: 'function';
+        function: Record<string, unknown>;
+    };
+    handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>;
+    echoUserSummaryOnSuccess?: boolean;
+    /**
+     * When true, the runtime will skip a second invocation of this tool in
+     * the same assistant message. Use for "create an agreement"-style tools
+     * where the model is prone to fire two near-identical create calls.
+     */
+    isAgreementCreation?: boolean;
+    /**
+     * When true, the runtime will execute this tool even when no state
+     * action is bound to it. Use for discovery tools (e.g. agent search,
+     * task board) that should always be callable.
+     */
+    isGenericFallback?: boolean;
+}
+export interface DefineToolOptions {
+    description?: string;
+    echoUserSummaryOnSuccess?: boolean;
+    isAgreementCreation?: boolean;
+    isGenericFallback?: boolean;
+}
+export declare function defineTool(name: string, params: Record<string, unknown>, handler: (args: Record<string, unknown>, context: Record<string, unknown>) => Promise<unknown>, options?: DefineToolOptions): ToolDefinition;

package/dist/tools/defineTool.js

@@ -0,0 +1,62 @@
+const PRIMITIVES = new Set(['string', 'number', 'boolean', 'integer']);
+function convertField(value) {
+    if (typeof value === 'string') {
+        if (!PRIMITIVES.has(value))
+            throw new Error(`Unknown type shorthand: "${value}"`);
+        return { schema: { type: value }, required: false };
+    }
+    if (Array.isArray(value)) {
+        if (value.length !== 1)
+            throw new Error('Array shorthand must have exactly one element describing the item type');
+        const inner = value[0];
+        if (typeof inner === 'string')
+            return { schema: { type: 'array', items: { type: inner } }, required: false };
+        return { schema: { type: 'array', items: convertObject(inner) }, required: false };
+    }
+    if (typeof value === 'object' && value !== null) {
+        const v = value;
+        if (v['type'] && PRIMITIVES.has(v['type'])) {
+            const { required: isReq, ...rest } = v;
+            return { schema: rest, required: !!isReq };
+        }
+        if (v['type'] === 'array' || v['type'] === 'object') {
+            const { required: isReq, ...rest } = v;
+            return { schema: rest, required: !!isReq };
+        }
+        return { schema: convertObject(v), required: false };
+    }
+    throw new Error(`Cannot convert field value: ${JSON.stringify(value)}`);
+}
+function convertObject(fields) {
+    const properties = {};
+    const required = [];
+    for (const [key, value] of Object.entries(fields)) {
+        if (key === 'required')
+            continue;
+        const { schema, required: isReq } = convertField(value);
+        properties[key] = schema;
+        if (isReq)
+            required.push(key);
+    }
+    const result = { type: 'object', properties };
+    if (required.length > 0)
+        result['required'] = required;
+    return result;
+}
+export function defineTool(name, params, handler, options = {}) {
+    if (!name || typeof name !== 'string')
+        throw new Error('defineTool: name is required');
+    if (!handler || typeof handler !== 'function')
+        throw new Error('defineTool: handler function is required');
+    const parameters = convertObject(params || {});
+    const fn = { name, parameters };
+    if (options.description)
+        fn['description'] = options.description;
+    return {
+        schema: { type: 'function', function: fn },
+        handler,
+        ...(options.echoUserSummaryOnSuccess ? { echoUserSummaryOnSuccess: true } : {}),
+        ...(options.isAgreementCreation ? { isAgreementCreation: true } : {}),
+        ...(options.isGenericFallback ? { isGenericFallback: true } : {}),
+    };
+}

package/{src/tools/index.ts → dist/tools/index.d.ts}

@@ -3,5 +3,4 @@ export { ToolProvider } from './ToolProvider.js';
 export { defineTool } from './defineTool.js';
 export { recordReport } from './recordReport.js';
 export type { RecordReportInput, RecordReportResult, TaskReport } from './recordReport.js';
-// Pure protocol-tool name registry (no handlers, no services).
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { ToolManager } from './ToolManager.js';
+export { ToolProvider } from './ToolProvider.js';
+export { defineTool } from './defineTool.js';
+export { recordReport } from './recordReport.js';
+// Pure protocol-tool name registry (no handlers, no services).
+export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';

package/dist/tools/recordReport.d.ts

@@ -0,0 +1,41 @@
+import { type Creds } from '@ziggs-ai/api-client';
+/**
+ * The canonical report shape (B1 convention — ZIG-561).
+ * Matches Task.result as set by ziggs_set_task_result.
+ */
+export interface TaskReport {
+    summary: string;
+    status?: string;
+    links?: string[];
+}
+export interface RecordReportInput {
+    creds: Creds;
+    taskId: string;
+    report: TaskReport;
+    /**
+     * Primary artifact scope — required when `deliverable` is provided.
+     * Pass exactly one of chatId or agreementId.
+     */
+    chatId?: string;
+    agreementId?: string;
+    /**
+     * Heavy deliverable text (document, diff, data).
+     * When present, writes a `content_type=result` artifact bound to the task
+     * alongside setting Task.result.
+     */
+    deliverable?: string;
+}
+export interface RecordReportResult {
+    taskId: string;
+    artifactId?: string;
+}
+/**
+ * Record a conformant report for a completed task (B2 — ZIG-562).
+ *
+ * Always sets Task.result via updateTaskState (the canonical done payload).
+ * When `deliverable` is provided, also writes a task-bound result artifact
+ * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
+ *
+ * Implements the B1 convention (Agents/REPORTING.md).
+ */
+export declare function recordReport(input: RecordReportInput): Promise<RecordReportResult>;