@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/dist/server/runLauncher.js

@@ -0,0 +1,93 @@
+import { ConnectionPool } from './ConnectionPool.js';
+import { AgentHost } from '../AgentHost.js';
+import { createHealthServer } from './createHealthServer.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+export async function runLauncher(configOrConfigs, opts = {}) {
+    if (Array.isArray(configOrConfigs))
+        return runFleet(configOrConfigs, opts);
+    return runSingle(configOrConfigs, opts);
+}
+async function runSingle(config, { operatorKey, label = 'agent', port = process.env.PORT || 8080, healthServer = true, onShutdown } = {}) {
+    const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+    const decorated = effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
+    const agent = new AgentHost(decorated);
+    try {
+        await agent.connectAsync();
+        runtimeLog.info(label, `"${agent['options'] ? (agent['options']?.agentId ?? agent['options']?.name) : 'agent'}" connected`);
+    }
+    catch (err) {
+        runtimeLog.warn(label, `Agent failed to connect at startup: ${err.message} — will retry`);
+    }
+    const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
+    process.on('SIGTERM', async () => {
+        runtimeLog.info(label, 'SIGTERM — shutting down');
+        agent.disconnect();
+        await agent.drain(30_000);
+        try {
+            await onShutdown?.();
+        }
+        catch (err) {
+            runtimeLog.warn(label, `onShutdown error: ${err.message}`);
+        }
+        server?.close();
+        process.exit(0);
+    });
+    return { agent, healthServer: server ?? undefined };
+}
+async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preWake = [], poolOptions, onShutdown, } = {}) {
+    const pool = new ConnectionPool(poolOptions);
+    const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+    const decoratedConfigs = effectiveKey
+        ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
+        : configs;
+    pool.register(decoratedConfigs, agentMeta);
+    const server = healthServer ? createHealthServer({ port: Number(port), label, pool }) : null;
+    let resolvedPrimaryConfig = typeof primaryConfig === 'function'
+        ? primaryConfig(pool)
+        : primaryConfig;
+    if (resolvedPrimaryConfig && effectiveKey && !resolvedPrimaryConfig.operatorKey) {
+        resolvedPrimaryConfig = { ...resolvedPrimaryConfig, operatorKey: effectiveKey };
+    }
+    const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedPrimaryConfig?.operatorKey;
+    if (controlKey) {
+        pool.startControl({ wsUrl, operatorKey: controlKey });
+    }
+    else {
+        runtimeLog.warn(label, 'No operatorKey provided — skipping control socket');
+    }
+    let primary = null;
+    if (resolvedPrimaryConfig) {
+        primary = new AgentHost(resolvedPrimaryConfig);
+        try {
+            await primary.connectAsync();
+            runtimeLog.info(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" connected`);
+        }
+        catch (err) {
+            // Backend may not be ready yet — socket.io reconnects automatically.
+            // Don't crash the process; the primary agent will be live once it reconnects.
+            runtimeLog.warn(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${err.message} — will retry`);
+        }
+    }
+    if (preWake.length > 0) {
+        await Promise.all(preWake.map(id => pool.wake(id)
+            .then(() => runtimeLog.debug(label, `Pre-woke "${id}"`))
+            .catch(err => runtimeLog.warn(label, `Could not pre-wake "${id}": ${err.message}`))));
+    }
+    runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+    process.on('SIGTERM', async () => {
+        runtimeLog.info(label, 'SIGTERM — shutting down');
+        pool.stopControl();
+        primary?.disconnect?.();
+        await primary?.drain?.(30_000);
+        await pool.disconnectAll();
+        try {
+            await onShutdown?.();
+        }
+        catch (err) {
+            runtimeLog.warn(label, `onShutdown error: ${err.message}`);
+        }
+        server?.close();
+        process.exit(0);
+    });
+    return { pool, primary, healthServer: server ?? undefined };
+}

package/dist/server/tasks/TaskService.d.ts

@@ -0,0 +1,25 @@
+import { type Task, type TaskState } from '@ziggs-ai/api-client';
+import type { CountTasksFilters } from '@ziggs-ai/api-client';
+export declare class TaskService {
+    private creds;
+    constructor(operatorKey: string, agentId: string);
+    getTask(taskId: string): Promise<Task>;
+    getActiveTasksForAgent(agentId: string): Promise<Task[]>;
+    getActiveTasksForChat(chatId: string): Promise<Task[]>;
+    getSubtasks(parentTaskId: string): Promise<Task[]>;
+    spawnUnderAgreement(agreementId: string, taskData: {
+        description: string;
+        parentTaskId?: string;
+        plan?: unknown;
+        planReviewTiming?: string;
+        requireMidWorkPlanAck?: boolean;
+        assigneeId?: string;
+        inputArtifactIds?: string[];
+    }): Promise<Task>;
+    updateState(taskId: string, state: TaskState, result?: unknown): Promise<Task>;
+    updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
+    cancel(taskId: string): Promise<Task>;
+    report(taskId: string, message?: string): Promise<Task>;
+    setSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task>;
+    count(filters?: CountTasksFilters): Promise<number>;
+}

package/dist/server/tasks/TaskService.js

@@ -0,0 +1,103 @@
+import { createTask, getTask, getActiveTasksForAgent, getActiveTasksForChat, getSubtasks, updateTaskState, updateTaskPlanStep, cancelTask, reportTask, setTaskSatisfaction, countTasks, } from '@ziggs-ai/api-client';
+import { runtimeLog } from '../../shared/runtimeLog.js';
+function safeJsonStringify(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value !== 'object')
+        return String(value);
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val))
+                    return '[Circular]';
+                seen.add(val);
+            }
+            return val;
+        }, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+export class TaskService {
+    creds;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('TaskService: operatorKey is required');
+        if (!agentId)
+            throw new Error('TaskService: agentId is required (operator-token impersonation)');
+        this.creds = { operatorKey, agentId };
+    }
+    async getTask(taskId) {
+        return getTask(taskId, this.creds);
+    }
+    async getActiveTasksForAgent(agentId) {
+        return getActiveTasksForAgent(agentId, this.creds);
+    }
+    async getActiveTasksForChat(chatId) {
+        return getActiveTasksForChat(chatId, this.creds);
+    }
+    async getSubtasks(parentTaskId) {
+        return getSubtasks(parentTaskId, this.creds);
+    }
+    async spawnUnderAgreement(agreementId, taskData) {
+        if (!agreementId)
+            throw new Error('TaskService.spawnUnderAgreement: agreementId is required');
+        try {
+            const result = await createTask({ ...taskData, agreementId }, this.creds);
+            runtimeLog.info('TaskService', `Task spawned under agreement ${agreementId}: ${result?.taskId || 'unknown'}`);
+            return result;
+        }
+        catch (error) {
+            const e = error;
+            runtimeLog.error('TaskService', `Task spawn failed (agreement ${agreementId}, assignee ${taskData.assigneeId ?? '-'}): status=${e.status ?? '?'} ${e.message}${e.body ? ` | body=${e.body}` : ''}`);
+            throw error;
+        }
+    }
+    async updateState(taskId, state, result) {
+        try {
+            const data = result !== undefined ? { result: safeJsonStringify(result) } : {};
+            const updated = await updateTaskState(taskId, state, data, this.creds);
+            runtimeLog.info('TaskService', `Task state: ${taskId} → ${state}`);
+            return updated;
+        }
+        catch (error) {
+            runtimeLog.error('TaskService', `Task state update failed: ${error.message}`);
+            throw error;
+        }
+    }
+    async updatePlanStep(taskId, stepId, status, result) {
+        try {
+            const updated = await updateTaskPlanStep(taskId, stepId, status, result, this.creds);
+            runtimeLog.info('TaskService', `Task plan step: ${taskId}/${stepId} → ${status}`);
+            return updated;
+        }
+        catch (error) {
+            runtimeLog.error('TaskService', `Task plan step update failed: ${error.message}`);
+            throw error;
+        }
+    }
+    async cancel(taskId) {
+        try {
+            const updated = await cancelTask(taskId, this.creds);
+            runtimeLog.info('TaskService', `Task cancelled: ${taskId}`);
+            return updated;
+        }
+        catch (error) {
+            runtimeLog.error('TaskService', `Task cancel failed: ${error.message}`);
+            throw error;
+        }
+    }
+    async report(taskId, message = '') {
+        return reportTask(taskId, message, this.creds);
+    }
+    async setSatisfaction(taskId, satisfaction) {
+        return setTaskSatisfaction(taskId, satisfaction, this.creds);
+    }
+    async count(filters = {}) {
+        return countTasks(filters, this.creds);
+    }
+}

package/dist/server/tasks/index.js

@@ -0,0 +1 @@
+export { TaskService } from './TaskService.js';

package/dist/server/telemetryIngest.d.ts

@@ -0,0 +1,24 @@
+import type { LlmResponse } from '../types.js';
+import type { TelemetryClient } from '@ziggs-ai/api-client';
+export declare function isTelemetryIngestEnabled(explicit?: boolean): boolean;
+export declare function usageFromLlmResponse(response: LlmResponse): {
+    tokensTotal: number;
+    tokensInput: number;
+    tokensOutput: number;
+};
+export declare function buildLlmIngestPayload(response: LlmResponse, ctx: {
+    sessionId?: string;
+    durationMs: number;
+    runId?: string;
+    stateId?: string;
+}): Record<string, unknown>;
+export declare function buildToolIngestPayload(ctx: {
+    sessionId: string;
+    tool: string;
+    durationMs: number;
+    ok: boolean;
+    runId?: string;
+    stateId?: string;
+}): Record<string, unknown>;
+/** Fire-and-forget; never throws to the effect handler. */
+export declare function sendTelemetry(client: TelemetryClient | undefined, payload: Record<string, unknown>, enabled: boolean): void;

package/dist/server/telemetryIngest.js

@@ -0,0 +1,62 @@
+export function isTelemetryIngestEnabled(explicit) {
+    if (explicit === false)
+        return false;
+    if (explicit === true)
+        return true;
+    const env = process.env.ZIGGS_TELEMETRY_INGEST;
+    if (env === '0' || env === 'false')
+        return false;
+    return true;
+}
+export function usageFromLlmResponse(response) {
+    const u = response.usage;
+    const tokensInput = Number(u?.prompt_tokens ?? u?.promptTokens ?? 0) || 0;
+    const tokensOutput = Number(u?.completion_tokens ?? u?.completionTokens ?? 0) || 0;
+    const tokensTotal = Number(u?.total_tokens ?? u?.totalTokens ?? 0) ||
+        tokensInput + tokensOutput;
+    return { tokensTotal, tokensInput, tokensOutput };
+}
+export function buildLlmIngestPayload(response, ctx) {
+    const { tokensTotal, tokensInput, tokensOutput } = usageFromLlmResponse(response);
+    const chatId = ctx.sessionId ?? null;
+    return {
+        source: 'agent',
+        chatId,
+        sessionId: chatId,
+        execution: {
+            llmCallsTotal: 1,
+            tokensTotal,
+            tokensInput,
+            tokensOutput,
+            ...(tokensTotal > 0 ? { tokensPerLlmCall: [tokensTotal] } : {}),
+        },
+        resource: { durationMs: Math.max(0, Math.round(ctx.durationMs)) },
+        meta: {
+            effect: 'llm-call',
+            ...(ctx.runId ? { runId: ctx.runId } : {}),
+            ...(ctx.stateId ? { stateId: ctx.stateId } : {}),
+        },
+    };
+}
+export function buildToolIngestPayload(ctx) {
+    return {
+        source: 'agent',
+        chatId: ctx.sessionId,
+        sessionId: ctx.sessionId,
+        execution: { executionLoops: 1 },
+        resource: { durationMs: Math.max(0, Math.round(ctx.durationMs)) },
+        meta: {
+            effect: 'tool-call',
+            tool: ctx.tool,
+            ok: ctx.ok,
+            ...(ctx.runId ? { runId: ctx.runId } : {}),
+            ...(ctx.stateId ? { stateId: ctx.stateId } : {}),
+        },
+    };
+}
+/** Fire-and-forget; never throws to the effect handler. */
+export function sendTelemetry(client, payload, enabled) {
+    if (!enabled || !client)
+        return;
+    void client.send(payload).catch(() => { });
+}

package/dist/server/tools/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent tool bundles, in two tiers. Single home for everything an agent can
+ * "speak" or "do" over the wire.
+ *
+ * Tier 1 — protocol grammar (tier1/). The verbs every agent uses to participate
+ * in the agreement/task system. Framework-managed: attached via the `taskTools`
+ * config (default 'all'), dispatched to in-process services (taskService /
+ * agreementService) injected into tool context — NOT passed in the user `tools:`
+ * array. Publishing open work is part of this grammar:
+ * agreement_propose({ proposedTo: "everyone" }) for a public broadcast, or
+ * proposedTo: "org" to scope it to your org — there is no separate publish tool.
+ *
+ * Tier 2 — capability bundles (tier2/). Opt-in, HTTP-backed tool bundles an agent
+ * chooses to have. Off by default; an agent gains a bundle by spreading it into
+ * its `tools:` array. Each tool reads operatorKey/agentId from tool context and
+ * wraps a backend HTTP client — no per-agent plumbing.
+ */
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
+export { dispatchProtocolOp } from './tier1/protocolRunner.js';
+export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
+export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';

package/{src/server/tools/index.ts → dist/server/tools/index.js}

@@ -15,32 +15,12 @@
  * its `tools:` array. Each tool reads operatorKey/agentId from tool context and
  * wraps a backend HTTP client — no per-agent plumbing.
  */
-
 // ── Tier 1: protocol grammar ────────────────────────────────────────────────
-export {
-  PROTOCOL_TOOLS,
-  agreementProposeTool, agreementSubcontractTool, agreementRespondTool,
-  agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool,
-  taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool,
-} from './tier1/protocolTools.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementCounterProposalTool, agreementCheckProposalTool, agreementRevokeTool, taskSpawnTool, taskUpdateTool, taskUpdatePlanStepTool, } from './tier1/protocolTools.js';
 export { dispatchProtocolOp } from './tier1/protocolRunner.js';
-
 // ── Tier 2: capability bundles ──────────────────────────────────────────────
 export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discoveryTools.js';
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
-export {
-  PAYMENT_TOOLS,
-  paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
-  paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
-  paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool,
-} from './tier2/paymentTools.js';
-export {
-  CONNECTION_TOOLS,
-  connectionProxyTool,
-  connectionListGrantsTool,
-} from './tier2/connectionTools.js';
-export {
-  CONTEXT_TOOLS,
-  contextDiscoverTool,
-  contextDelegateTool,
-} from './tier2/contextTools.js';
+export { PAYMENT_TOOLS, paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool, paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool, paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool, } from './tier2/paymentTools.js';
+export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, } from './tier2/connectionTools.js';
+export { CONTEXT_TOOLS, contextDiscoverTool, contextDelegateTool, } from './tier2/contextTools.js';

package/dist/server/tools/tier1/protocolRunner.d.ts

@@ -0,0 +1,39 @@
+import type { AgreementService } from '../../agreements/AgreementService.js';
+import type { TaskService } from '../../tasks/TaskService.js';
+import type { ContextReadClient } from '@ziggs-ai/api-client';
+interface Services {
+    agreementService: AgreementService;
+    taskService: TaskService;
+    contextReadClient: ContextReadClient;
+}
+interface ProtocolPayload {
+    operation?: string;
+    agreementId?: string;
+    description?: string;
+    proposedTo?: string;
+    providerId?: string;
+    executorId?: string;
+    action?: 'approve' | 'reject';
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    agreementDescription?: string;
+    parentAgreementId?: string;
+    parentTaskId?: string;
+    taskId?: string;
+    stepId?: string;
+    assigneeId?: string;
+    status?: string;
+    result?: unknown;
+    plan?: unknown;
+    planReviewTiming?: string;
+    requireMidWorkPlanAck?: boolean;
+    engagementKind?: 'hire' | 'service';
+    subtasks?: (string | {
+        description?: string;
+    })[];
+    [key: string]: unknown;
+}
+export declare function dispatchProtocolOp(services: Services, payload: ProtocolPayload, chatId: string | null, agents?: unknown[], actingAgentId?: string | null): Promise<unknown>;
+export {};