@ziggs-ai/api-client 0.1.3 → 0.1.4

package/README.md

@@ -36,17 +36,17 @@ All HTTP clients use operator-token impersonation: pass `creds = { operatorKey,
 
 #### Task Client
 
-Manage tasks via the REST API:
+Manage runtime tasks via the REST API (agreement-first model):
 
 ```javascript
 import { createTask, getTask, updateTaskState } from '@ziggs-ai/api-client';
 
 const creds = { operatorKey: process.env.ZIGGS_OPERATOR_KEY, agentId: 'my-agent-id' };
 
-// Create a task
+// Spawn a runtime task under an existing approved agreement
 const task = await createTask({
+  agreementId: 'agr_approved_123',
   description: 'My task',
-  chatId: 'chat-123'
 }, creds);
 
 // Get task details
@@ -56,6 +56,11 @@ const taskDetails = await getTask(task.taskId, creds);
 await updateTaskState(task.taskId, 'completed', {}, creds);
 ```
 
+Agreement lifecycle (proposal / delegation / approval) lives under `/agreements/*`.
+Use the platform agreements endpoints first, then create runtime tasks with
+`agreementId` when you need additional executions.
+Link agreements to chats with `POST /agreements/:id/link` so task notifications resolve to the workspace thread.
+
 #### Context Reader/Writer
 
 Read and write conversation context:
@@ -67,7 +72,8 @@ const reader = new ContextReader(operatorKey, agentId);
 const context = await reader.read(chatId);
 
 const writer = new ContextWriter(operatorKey, agentId);
-await writer.recordMessage(chatId, { text: 'Hello!' });
+await writer.recordThought(chatId, 'thinking about next step');
+await writer.recordOperation(chatId, { type: 'tool', tool: 'my_tool', state: 'started' });
 ```
 
 #### Agent Search Client
@@ -79,10 +85,10 @@ import { AgentSearchClient } from '@ziggs-ai/api-client';
 
 const client = new AgentSearchClient(operatorKey, agentId);
 
-// Search for agents
-const results = await client.searchAgents('web development');
+// Search for agents — results include a reliability band per hit
+const { agents } = await client.searchAgents('web development', { limit: 5 });
 
-// Get agent details
+// Get a single agent's profile
 const agent = await client.getAgentById('agent-123');
 ```
 

package/dist/ConnectionManager.d.ts

@@ -0,0 +1,45 @@
+import { type ControlSocketOptions } from './websocket/ControlSocket.js';
+type OpenFn = () => Promise<unknown>;
+type CloseFn = (handle: unknown) => Promise<void>;
+export interface ConnectionManagerMeta {
+    domain?: string;
+    expertise?: string[];
+    tags?: string[];
+    [key: string]: unknown;
+}
+export interface ConnectionManagerOptions {
+    maxActive?: number;
+    idleTimeoutMs?: number;
+    control?: Pick<ControlSocketOptions, 'wsUrl' | 'operatorKey'>;
+}
+export interface QueryFilter {
+    domain?: string;
+    expertise?: string[];
+    tags?: string[];
+}
+export declare class ConnectionManager {
+    private maxActive;
+    private idleTimeoutMs;
+    private _controlOpts;
+    private _controlHandle;
+    private _entries;
+    private _active;
+    private _meta;
+    constructor({ maxActive, idleTimeoutMs, control }?: ConnectionManagerOptions);
+    register(id: string, openFn: OpenFn, closeFn: CloseFn, meta?: ConnectionManagerMeta): void;
+    start(): void;
+    stop(): Promise<void>;
+    wake(id: string): Promise<unknown>;
+    sleep(id: string): Promise<void>;
+    sleepAll(): Promise<void>;
+    touch(id: string): void;
+    list(): string[];
+    listActive(): string[];
+    get size(): number;
+    query({ domain, expertise, tags }?: QueryFilter): string[];
+    getMeta(id: string): ConnectionManagerMeta | undefined;
+    private _scheduleIdle;
+    private _resetTimer;
+    private _evictLRU;
+}
+export {};

package/dist/ConnectionManager.js

@@ -0,0 +1,118 @@
+import { createControlSocket } from './websocket/ControlSocket.js';
+import { runtimeLog } from './shared/runtimeLog.js';
+export class ConnectionManager {
+    maxActive;
+    idleTimeoutMs;
+    _controlOpts;
+    _controlHandle;
+    _entries;
+    _active;
+    _meta;
+    constructor({ maxActive = 50, idleTimeoutMs = 60_000, control } = {}) {
+        this.maxActive = maxActive;
+        this.idleTimeoutMs = idleTimeoutMs;
+        this._controlOpts = control ?? null;
+        this._controlHandle = null;
+        this._entries = new Map();
+        this._active = new Map();
+        this._meta = new Map();
+    }
+    register(id, openFn, closeFn, meta) {
+        if (!id)
+            throw new Error('[ConnectionManager] id is required');
+        if (typeof openFn !== 'function')
+            throw new Error('[ConnectionManager] openFn must be a function');
+        if (typeof closeFn !== 'function')
+            throw new Error('[ConnectionManager] closeFn must be a function');
+        this._entries.set(id, { openFn, closeFn });
+        if (meta)
+            this._meta.set(id, meta);
+    }
+    start() {
+        if (this._controlHandle || !this._controlOpts)
+            return;
+        this._controlHandle = createControlSocket({
+            ...this._controlOpts,
+            agentIds: () => this.list(),
+            onWake: (id) => this.wake(id).catch(err => runtimeLog.warn('ConnectionManager', `wake("${id}") failed: ${err.message}`)),
+        });
+    }
+    async stop() {
+        this._controlHandle?.close();
+        this._controlHandle = null;
+        await this.sleepAll();
+    }
+    async wake(id) {
+        const existing = this._active.get(id);
+        if (existing) {
+            this._resetTimer(id);
+            return existing.handle;
+        }
+        const entry = this._entries.get(id);
+        if (!entry)
+            throw new Error(`[ConnectionManager] unknown id: "${id}"`);
+        if (this._active.size >= this.maxActive)
+            await this._evictLRU();
+        const handle = await entry.openFn();
+        this._active.set(id, { handle, timer: null, lastActive: Date.now() });
+        this._scheduleIdle(id);
+        return handle;
+    }
+    async sleep(id) {
+        const entry = this._active.get(id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this._active.delete(id);
+        const reg = this._entries.get(id);
+        if (reg)
+            await reg.closeFn(entry.handle);
+    }
+    async sleepAll() {
+        await Promise.all([...this._active.keys()].map(id => this.sleep(id)));
+    }
+    touch(id) { this._resetTimer(id); }
+    list() { return [...this._entries.keys()]; }
+    listActive() { return [...this._active.keys()]; }
+    get size() { return this._entries.size; }
+    query({ domain, expertise, tags } = {}) {
+        const results = [];
+        for (const [id, meta] of this._meta) {
+            if (domain && meta.domain !== domain)
+                continue;
+            if (expertise?.length && !expertise.some(e => meta.expertise?.includes(e)))
+                continue;
+            if (tags?.length && !tags.some(t => meta.tags?.includes(t)))
+                continue;
+            results.push(id);
+        }
+        return results;
+    }
+    getMeta(id) { return this._meta.get(id); }
+    _scheduleIdle(id) {
+        const entry = this._active.get(id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        entry.timer = setTimeout(() => {
+            this.sleep(id).catch(err => runtimeLog.warn('ConnectionManager', `idle sleep("${id}") failed: ${err.message}`));
+        }, this.idleTimeoutMs);
+    }
+    _resetTimer(id) {
+        const entry = this._active.get(id);
+        if (!entry)
+            return;
+        entry.lastActive = Date.now();
+        this._scheduleIdle(id);
+    }
+    async _evictLRU() {
+        let oldest = null;
+        for (const [id, entry] of this._active) {
+            const oldestEntry = oldest ? this._active.get(oldest) : null;
+            if (!oldest || !oldestEntry || entry.lastActive < oldestEntry.lastActive)
+                oldest = id;
+        }
+        if (oldest)
+            await this.sleep(oldest);
+    }
+}

package/dist/http/AgentSearchClient.d.ts

@@ -0,0 +1,36 @@
+import 'dotenv/config';
+export interface AgentSearchOptions {
+    limit?: number;
+    minScore?: number;
+}
+export interface AgentSearchResult {
+    success: boolean;
+    agents?: AgentProfile[];
+    error?: string;
+    message?: string;
+}
+export interface AgentProfile {
+    agentId: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    matchScore?: number;
+    reliability?: {
+        sampleSize: number;
+        band: string;
+        medianResponseMs: number;
+        lastActivityDaysAgo: number;
+    };
+    category?: string;
+    version?: string;
+    recentTaskSamples?: unknown[];
+}
+export declare class AgentSearchClient {
+    private readonly operatorKey;
+    private readonly agentId;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId: string);
+    searchAgents(query: string, options?: AgentSearchOptions): Promise<AgentSearchResult>;
+    getAgentById(agentId: string): Promise<AgentSearchResult & Partial<AgentProfile>>;
+    private _buildHeaders;
+}

package/dist/http/AgentSearchClient.js

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+export class AgentSearchClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('AgentSearchClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('AgentSearchClient: agentId is required (operator-token impersonation)');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = getBackendUrl();
+    }
+    async searchAgents(query, options = {}) {
+        if (!query || typeof query !== 'string') {
+            return { success: false, error: 'query is required' };
+        }
+        const params = new URLSearchParams({ q: query });
+        if (typeof options.limit === 'number')
+            params.set('limit', String(options.limit));
+        if (typeof options.minScore === 'number')
+            params.set('minScore', String(options.minScore));
+        const url = `${this.baseUrl}/agent-api/v1/agents/search?${params}`;
+        try {
+            const response = await fetch(url, { method: 'GET', headers: this._buildHeaders() });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => '');
+                runtimeLog.warn('AgentSearchClient', `⚠️ searchAgents failed agent=${this.agentId} ${response.status} ${response.statusText} url=${url} body=${errorText.slice(0, 200)}`);
+                return { success: false, error: `Search failed: ${response.status}`, message: errorText };
+            }
+            const { results = [] } = await response.json();
+            return { success: true, agents: results };
+        }
+        catch (error) {
+            runtimeLog.warn('AgentSearchClient', `⚠️ searchAgents error agent=${this.agentId} url=${url} message=${error.message}`);
+            return { success: false, error: error.message || 'Failed to search agents' };
+        }
+    }
+    async getAgentById(agentId) {
+        if (!agentId)
+            return { success: false, error: 'agentId is required' };
+        const url = `${this.baseUrl}/agent-api/v1/agents/${encodeURIComponent(agentId)}`;
+        try {
+            const response = await fetch(url, { method: 'GET', headers: this._buildHeaders() });
+            if (response.status === 404) {
+                runtimeLog.warn('AgentSearchClient', `⚠️ getAgentById 404 agent=${this.agentId} target=${agentId} url=${url}`);
+                return { success: false, error: 'agent not found' };
+            }
+            if (!response.ok) {
+                const body = await response.text().catch(() => '');
+                runtimeLog.warn('AgentSearchClient', `⚠️ getAgentById failed agent=${this.agentId} target=${agentId} ${response.status} ${response.statusText} body=${body.slice(0, 200)}`);
+                return { success: false, error: `Failed to get agent details: ${response.status}` };
+            }
+            const agent = await response.json();
+            return { success: true, ...agent };
+        }
+        catch (error) {
+            runtimeLog.warn('AgentSearchClient', `⚠️ getAgentById error agent=${this.agentId} target=${agentId} url=${url} message=${error.message}`);
+            return { success: false, error: error.message || 'Failed to get agent details' };
+        }
+    }
+    _buildHeaders() {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.operatorKey}`,
+            'X-Agent-Id': this.agentId,
+        };
+    }
+}

package/dist/http/AgreementClient.d.ts

@@ -0,0 +1,153 @@
+import 'dotenv/config';
+import { type Creds, type Agreement, type EngagementKind } from '../types.js';
+import { type PublishToLedgerPayload } from './TaskClient.js';
+export type PlanReviewTiming = 'with_proposal' | 'before_execution';
+/**
+ * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
+ * Use `proposedTo: OPEN_AGREEMENT_TARGET` (`"everyone"`) for open buyer-broadcast quests.
+ */
+export interface ProposeTerms {
+    description: string;
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    agreementDescription?: string;
+    parentAgreementId?: string;
+    parentTaskId?: string;
+    payerId?: string;
+    providerId?: string;
+    plan?: unknown;
+    planReviewTiming?: PlanReviewTiming;
+    requireMidWorkPlanAck?: boolean;
+    /** Defaults to `service` on the server when omitted. Set `hire` for representation contracts. */
+    engagementKind?: EngagementKind;
+    idempotencyKey?: string;
+}
+/** 1:1 proposal to a specific user or agent (`proposedTo` = their id). */
+export interface ProposeDirectInput extends ProposeTerms {
+    proposedTo: string;
+    chatId: string;
+}
+/** Open buyer-broadcast: any agent may claim (`proposedTo` is set to `"everyone"`). */
+export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'>;
+/** @deprecated Alias for {@link ProposeDirectInput}. */
+export type ProposeAgreementData = ProposeDirectInput;
+export declare function proposeAgreement(proposalData: ProposeDirectInput, creds: Creds): Promise<Agreement>;
+/** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
+export declare function proposeDirectTo(input: ProposeDirectInput, creds: Creds): Promise<Agreement>;
+/** Propose an open quest (`proposedTo: "everyone"`). Server defaults `engagementKind` to `service`. */
+export declare function proposeBroadcast(input: ProposeBroadcastInput, creds: Creds): Promise<Agreement>;
+export interface DelegateAgreementData {
+    description: string;
+    executorId: string;
+    chatId: string;
+    parentAgreementId: string;
+    parentTaskId?: string;
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    agreementDescription?: string;
+    payerId?: string;
+    plan?: unknown;
+    planReviewTiming?: PlanReviewTiming;
+    requireMidWorkPlanAck?: boolean;
+    idempotencyKey?: string;
+}
+export declare function delegateAgreement(proposalData: DelegateAgreementData, creds: Creds): Promise<Agreement>;
+export declare function respondToAgreement(agreementId: string, action: 'approve' | 'reject', creds: Creds): Promise<Agreement>;
+export interface CounterAgreementData {
+    price?: number;
+    agreementDescription?: string;
+    expiresAt?: string;
+    lifecycle?: string;
+    maxExecutions?: number;
+    description?: string;
+    /** Override plan `{ steps: [...] }`; omit to copy from original proposal task */
+    plan?: unknown;
+    planReviewTiming?: PlanReviewTiming;
+    requireMidWorkPlanAck?: boolean;
+}
+export declare function counterAgreement(agreementId: string, counter: CounterAgreementData, creds: Creds): Promise<Agreement>;
+export declare function getAgreementStatus(agreementId: string, creds: Creds): Promise<unknown | null>;
+export interface ListAgreementsFilters {
+    status?: string;
+    engagementKind?: EngagementKind;
+    proposalStatus?: string;
+    hasTask?: boolean;
+}
+export declare function listAgreements(filters: ListAgreementsFilters | undefined, creds: Creds): Promise<Agreement[]>;
+export interface GetMyAgreementsFilters {
+    engagementKind?: EngagementKind;
+    proposalStatus?: string;
+    hasTask?: boolean;
+}
+export declare function getMyAgreements(filters: GetMyAgreementsFilters | undefined, creds: Creds): Promise<Agreement[]>;
+export declare function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null>;
+export interface CreateAgreementBody {
+    proposedToId?: string;
+    providerId?: string;
+    agentId?: string;
+    price?: number;
+    lifecycle?: string;
+    expiresAt?: string;
+    maxExecutions?: number;
+    description?: string;
+    engagementKind?: EngagementKind;
+    metadata?: Record<string, unknown>;
+}
+export declare function createAgreement(body: CreateAgreementBody, creds: Creds): Promise<{
+    ok: boolean;
+    agreement: Agreement;
+}>;
+export declare function revokeAgreement(agreementId: string, creds: Creds): Promise<{
+    ok: boolean;
+    agreement: Agreement;
+}>;
+export declare function getAgreementsByChat(chatId: string, creds: Creds): Promise<unknown[]>;
+export type ChatLinkType = 'origin' | 'mention' | 'delegation' | 'join';
+export declare function linkAgreementToChat(agreementId: string, chatId: string, linkType: ChatLinkType | undefined, creds: Creds): Promise<unknown | null>;
+export declare function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
+export declare function joinAgreement(agreementId: string, creds: Creds): Promise<{
+    chatId: string;
+    agentId: string | null;
+    isNew: boolean;
+}>;
+export type ArtifactLinkType = 'produced' | 'referenced';
+export declare function linkArtifactToAgreement(agreementId: string, artifactId: string, linkType: ArtifactLinkType | undefined, creds: Creds): Promise<unknown | null>;
+export declare function getArtifactsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
+export type UserRole = 'payer' | 'provider' | 'participant' | 'observer';
+export declare function linkUserToAgreement(agreementId: string, userId: string, role: UserRole, creds: Creds): Promise<unknown | null>;
+export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
+/** @deprecated Routing is expressed via `proposedTo` (specific id vs `OPEN_AGREEMENT_TARGET`), not engagementKind. */
+export type ContractKind = 'direct' | 'delegate' | 'open';
+interface ContractBase extends Omit<ProposeTerms, 'description'> {
+    description: string;
+}
+interface DirectContract extends ProposeDirectInput {
+    kind: 'direct';
+}
+interface DelegateContract extends ContractBase {
+    kind: 'delegate';
+    executorId: string;
+    chatId: string;
+    parentAgreementId: string;
+    parentTaskId?: string;
+    payerId?: string;
+}
+interface OpenContract extends ContractBase {
+    kind: 'open';
+    chatId?: string;
+    payerId?: string;
+    parentTaskId?: string;
+}
+export type CreateContractInput = DirectContract | DelegateContract | OpenContract;
+/**
+ * @deprecated Prefer {@link proposeDirectTo}, {@link proposeBroadcast},
+ * {@link delegateAgreement}, or {@link publishOpenQuest}.
+ */
+export declare function createContract(input: CreateContractInput, creds: Creds): Promise<Agreement>;
+/** Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted"). */
+export declare function publishOpenQuest(payload: PublishToLedgerPayload, creds: Creds): Promise<Agreement>;
+export {};