@ziggs-ai/api-client 0.1.11 → 0.1.13

package/README.md

@@ -61,21 +61,56 @@ 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
+#### Context Clients
 
-Read and write conversation context:
+The old `ContextReader` / `ContextWriter` types were removed. Use the protocol-first clients:
 
 ```javascript
-import { ContextReader, ContextWriter } from '@ziggs-ai/api-client';
+import {
+  ContextReadClient,
+  ContextDiscoveryClient,
+  ContextGrantsClient,
+  ArtifactsClient,
+  InboxClient,
+  MessagesClient,
+  ScopeClient,
+} from '@ziggs-ai/api-client';
+
+const operatorKey = process.env.ZIGGS_OPERATOR_KEY;
+const agentId = 'my-agent-id';
+
+// Read messages, artifacts, agreements, or tasks via a scope entry point
+const reader = new ContextReadClient(operatorKey, agentId);
+const result = await reader.read('messages', { via: 'chat:<chatId>', after: '<iso>' });
+
+// Discover all scopes this delegate can reach (grants only, no content)
+const discovery = new ContextDiscoveryClient(operatorKey, agentId);
+const reach = await discovery.discover();
+
+// Manage context grants
+const grants = new ContextGrantsClient(operatorKey, agentId);
+const grant = await grants.issueGrant({
+  holderId: agentId,
+  scope: { kind: 'chat', id: '<chatId>' },
+  temporal: 'from-now',
+});
 
-const reader = new ContextReader(operatorKey, agentId);
-const context = await reader.read(chatId);
+// Write artifacts (thoughts, breadcrumbs, outputs)
+const artifacts = new ArtifactsClient(operatorKey, agentId);
+await artifacts.write({
+  text: 'thinking about next step',
+  visibility: 'agent-private',
+  chatId: '<chatId>',
+});
 
-const writer = new ContextWriter(operatorKey, agentId);
-await writer.recordThought(chatId, 'thinking about next step');
-await writer.recordOperation(chatId, { type: 'tool', tool: 'my_tool', state: 'started' });
+// Inbox loop: references since last ack (inbox → read → act → ack)
+const inbox = new InboxClient(operatorKey, agentId);
+const env = await inbox.getInbox();
+await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
 ```
 
+Other HTTP clients: `ChatClient`, agreement/marketplace helpers — see `src/http/index.ts`.
+
 #### Agent Search Client
 
 Search for agents:

package/dist/http/AgreementClient.d.ts

@@ -56,7 +56,33 @@ export interface DelegateAgreementData {
     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>;
+/**
+ * Approve or reject a pending agreement (ZIG-524 canonical client path).
+ *
+ * Routes to `POST /claim` (open broadcast) or `PUT /approvals/:partyId` (ledger).
+ * Legacy rows without approvals[] are backfilled server-side on PUT.
+ */
+export declare function respondToAgreement(agreementId: string, action: 'approve' | 'reject', creds: Creds, opts?: {
+    ownerUserId?: string | null;
+    agreement?: Agreement | null;
+}): Promise<Agreement>;
+/**
+ * ZIG-524 — resolve which approvals.partyId the current operator may submit.
+ * Checks pending ledger entries against impersonated agent id and owner principal.
+ */
+export declare function resolveMyPendingApprovalPartyId(agreement: Agreement, opts: {
+    ownerUserId?: string | null;
+    agentId?: string | null;
+}): string | null;
+/**
+ * Record this party's approval decision on an agreement
+ * (`PUT /agreements/:agreementId/approvals/:partyId`).
+ *
+ * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
+ * principal when approving as human, delegate agent id when impersonating.
+ * Canonical for hire, service, link, and quest proposals (ZIG-524).
+ */
+export declare function approveAgreementAsParty(agreementId: string, partyId: string, status: 'approved' | 'rejected', creds: Creds): Promise<Agreement>;
 export interface CounterAgreementData {
     price?: number;
     agreementDescription?: string;
@@ -105,6 +131,24 @@ export declare function revokeAgreement(agreementId: string, creds: Creds): Prom
     ok: boolean;
     agreement: Agreement;
 }>;
+/**
+ * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
+ * - open link invite (`engagementKind: link`, proposedTo everyone)
+ * - open broadcast quest (proposedTo everyone, status open)
+ *
+ * POST /agreements/:id/claim — canonical; no partyId in body.
+ */
+export declare function claimAgreement(agreementId: string, creds: Creds): Promise<{
+    ok: boolean;
+    agreement: Agreement;
+}>;
+/**
+ * @deprecated Use {@link claimAgreement} — same endpoint, clearer name for link + quest.
+ */
+export declare function claimLink(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>;
@@ -150,4 +194,48 @@ export type CreateContractInput = DirectContract | DelegateContract | OpenContra
 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 declare class AgreementClient {
+    private creds;
+    constructor(operatorKey: string, agentId: string);
+    propose(data: ProposeDirectInput): Promise<Agreement>;
+    proposeDirect(data: ProposeDirectInput): Promise<Agreement>;
+    proposeBroadcast(data: ProposeBroadcastInput): Promise<Agreement>;
+    delegate(data: DelegateAgreementData): Promise<Agreement>;
+    respond(id: string, action: 'approve' | 'reject'): Promise<Agreement>;
+    approveAsParty(id: string, partyId: string, status: 'approved' | 'rejected'): Promise<Agreement>;
+    counter(id: string, data: CounterAgreementData): Promise<Agreement>;
+    getStatus(id: string): Promise<unknown>;
+    list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
+    listMine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
+    get(id: string): Promise<Agreement | null>;
+    create(data: CreateAgreementBody): Promise<{
+        ok: boolean;
+        agreement: Agreement;
+    }>;
+    revoke(id: string): Promise<{
+        ok: boolean;
+        agreement: Agreement;
+    }>;
+    claimAgreement(id: string): Promise<{
+        ok: boolean;
+        agreement: Agreement;
+    }>;
+    /** @deprecated use claimAgreement */
+    claimLink(id: string): Promise<{
+        ok: boolean;
+        agreement: Agreement;
+    }>;
+    listByChat(chatId: string): Promise<unknown[]>;
+    linkToChat(id: string, chatId: string, linkType?: ChatLinkType): Promise<unknown>;
+    listChats(id: string): Promise<unknown[]>;
+    join(id: string): Promise<{
+        chatId: string;
+        agentId: string | null;
+        isNew: boolean;
+    }>;
+    linkArtifact(id: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown>;
+    listArtifacts(id: string): Promise<unknown[]>;
+    linkUser(id: string, userId: string, role: UserRole): Promise<unknown>;
+    listUsers(id: string): Promise<unknown[]>;
+}
 export {};

package/dist/http/AgreementClient.js

@@ -103,22 +103,82 @@ export async function delegateAgreement(proposalData, creds) {
     }
     return data['agreement'];
 }
-export async function respondToAgreement(agreementId, action, creds) {
+/**
+ * Approve or reject a pending agreement (ZIG-524 canonical client path).
+ *
+ * Routes to `POST /claim` (open broadcast) or `PUT /approvals/:partyId` (ledger).
+ * Legacy rows without approvals[] are backfilled server-side on PUT.
+ */
+export async function respondToAgreement(agreementId, action, creds, opts = {}) {
     if (!agreementId || !action)
         throw new Error('Agreement ID and action are required for proposal response');
     assertCreds(creds, 'proposal response');
-    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/respond`, {
-        method: 'POST',
+    const agreement = opts.agreement ?? (await getAgreement(agreementId, creds));
+    if (!agreement) {
+        throw new Error(`Agreement ${agreementId} not found`);
+    }
+    const proposedTo = agreement.parties?.proposedTo;
+    if (proposedTo === OPEN_AGREEMENT_TARGET) {
+        if (action === 'reject')
+            return agreement;
+        const { agreement: updated } = await claimAgreement(agreementId, creds);
+        return updated;
+    }
+    const partyId = resolveMyPendingApprovalPartyId(agreement, {
+        ownerUserId: opts.ownerUserId,
+        agentId: creds.agentId,
+    });
+    if (!partyId) {
+        throw new Error(`No pending approval entry for this operator on agreement ${agreementId}`);
+    }
+    return approveAgreementAsParty(agreementId, partyId, action === 'approve' ? 'approved' : 'rejected', creds);
+}
+/**
+ * ZIG-524 — resolve which approvals.partyId the current operator may submit.
+ * Checks pending ledger entries against impersonated agent id and owner principal.
+ */
+export function resolveMyPendingApprovalPartyId(agreement, opts) {
+    const actorIds = [opts.agentId, opts.ownerUserId].filter((id) => typeof id === 'string' && id.length > 0);
+    const pending = (agreement.approvals ?? []).filter((a) => a.status === 'pending' || a.status === 'PENDING');
+    for (const id of actorIds) {
+        const hit = pending.find((a) => a.partyId === id);
+        if (hit)
+            return hit.partyId;
+    }
+    const proposedTo = agreement.parties?.proposedTo;
+    if (proposedTo &&
+        actorIds.includes(proposedTo) &&
+        (pending.length === 0 || pending.some((a) => a.partyId === proposedTo))) {
+        return proposedTo;
+    }
+    return null;
+}
+/**
+ * Record this party's approval decision on an agreement
+ * (`PUT /agreements/:agreementId/approvals/:partyId`).
+ *
+ * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
+ * principal when approving as human, delegate agent id when impersonating.
+ * Canonical for hire, service, link, and quest proposals (ZIG-524).
+ */
+export async function approveAgreementAsParty(agreementId, partyId, status, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required for approval');
+    if (!partyId)
+        throw new Error('partyId (caller owner principal) is required for approval');
+    assertCreds(creds, 'agreement approval');
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/approvals/${encodeURIComponent(partyId)}`, {
+        method: 'PUT',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ action }),
+        body: JSON.stringify({ status }),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
-        throwApiError(res, body, `Proposal response failed: ${res.status} ${res.statusText}`);
+        throwApiError(res, body, `Agreement approval failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { agreement } from /agreements/:id/respond');
+        throw new Error('Invalid response: expected { agreement } from PUT /agreements/:id/approvals/:partyId');
     }
     return data['agreement'];
 }
@@ -282,6 +342,34 @@ export async function revokeAgreement(agreementId, creds) {
     }
     return data;
 }
+/**
+ * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
+ * - open link invite (`engagementKind: link`, proposedTo everyone)
+ * - open broadcast quest (proposedTo everyone, status open)
+ *
+ * POST /agreements/:id/claim — canonical; no partyId in body.
+ */
+export async function claimAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required to claim an open agreement');
+    assertCreds(creds, 'open agreement claim');
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/claim`, { method: 'POST', headers: buildHeaders(creds) });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Open agreement claim failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/claim');
+    }
+    return data;
+}
+/**
+ * @deprecated Use {@link claimAgreement} — same endpoint, clearer name for link + quest.
+ */
+export async function claimLink(agreementId, creds) {
+    return claimAgreement(agreementId, creds);
+}
 // ---------------------------------------------------------------------------
 // Chat links
 // ---------------------------------------------------------------------------
@@ -475,3 +563,37 @@ export async function createContract(input, creds) {
 export async function publishOpenQuest(payload, creds) {
     return publishToLedger(payload, creds);
 }
+export class AgreementClient {
+    creds;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('AgreementClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('AgreementClient: agentId is required');
+        this.creds = { operatorKey, agentId };
+    }
+    propose(data) { return proposeAgreement(data, this.creds); }
+    proposeDirect(data) { return proposeDirectTo(data, this.creds); }
+    proposeBroadcast(data) { return proposeBroadcast(data, this.creds); }
+    delegate(data) { return delegateAgreement(data, this.creds); }
+    respond(id, action) { return respondToAgreement(id, action, this.creds); }
+    approveAsParty(id, partyId, status) { return approveAgreementAsParty(id, partyId, status, this.creds); }
+    counter(id, data) { return counterAgreement(id, data, this.creds); }
+    getStatus(id) { return getAgreementStatus(id, this.creds); }
+    list(filters) { return listAgreements(filters, this.creds); }
+    listMine(filters) { return getMyAgreements(filters, this.creds); }
+    get(id) { return getAgreement(id, this.creds); }
+    create(data) { return createAgreement(data, this.creds); }
+    revoke(id) { return revokeAgreement(id, this.creds); }
+    claimAgreement(id) { return claimAgreement(id, this.creds); }
+    /** @deprecated use claimAgreement */
+    claimLink(id) { return claimAgreement(id, this.creds); }
+    listByChat(chatId) { return getAgreementsByChat(chatId, this.creds); }
+    linkToChat(id, chatId, linkType) { return linkAgreementToChat(id, chatId, linkType ?? 'mention', this.creds); }
+    listChats(id) { return getChatsForAgreement(id, this.creds); }
+    join(id) { return joinAgreement(id, this.creds); }
+    linkArtifact(id, artifactId, linkType) { return linkArtifactToAgreement(id, artifactId, linkType ?? 'produced', this.creds); }
+    listArtifacts(id) { return getArtifactsForAgreement(id, this.creds); }
+    linkUser(id, userId, role) { return linkUserToAgreement(id, userId, role, this.creds); }
+    listUsers(id) { return getUsersForAgreement(id, this.creds); }
+}

package/dist/http/ChatClient.d.ts

@@ -61,3 +61,13 @@ export declare function addChatMember(input: AddChatMemberInput, creds: Creds):
  */
 export declare function sendChatMessage(input: SendChatMessageInput, creds: Creds): Promise<SendChatMessageResult>;
 export declare function listMyChats(creds: Creds): Promise<ChatSummary[]>;
+export declare class ChatClient {
+    private creds;
+    constructor(operatorKey: string, agentId: string);
+    open(participantId: string): Promise<{
+        chatId: string;
+    }>;
+    addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
+    sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;
+    listMine(): Promise<ChatSummary[]>;
+}

package/dist/http/ChatClient.js

@@ -130,3 +130,17 @@ export async function listMyChats(creds) {
         return [];
     }
 }
+export class ChatClient {
+    creds;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('ChatClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('ChatClient: agentId is required');
+        this.creds = { operatorKey, agentId };
+    }
+    open(participantId) { return openConversation(participantId, this.creds); }
+    addMember(input) { return addChatMember(input, this.creds); }
+    sendMessage(input) { return sendChatMessage(input, this.creds); }
+    listMine() { return listMyChats(this.creds); }
+}

package/dist/http/InboxClient.d.ts

@@ -15,12 +15,20 @@ export interface InboxProposalRef {
     title: string;
     proposedAt: string | null;
 }
-/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482). */
+export interface InboxConnectionRequestRef {
+    requestId: string;
+    requesterAgentId: string;
+    message: string | null;
+    requestedAt: string | null;
+}
+/** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482 / ZIG-481). */
 export interface InboxHumanAttention {
     required: true;
-    reason: 'proposals_awaiting_me';
+    reason: 'proposals_awaiting_me' | 'connection_requests_awaiting_me' | 'multiple';
     proposalCount: number;
     truncatedProposals: number;
+    connectionRequestCount: number;
+    truncatedConnectionRequests: number;
     promptUser: string;
 }
 export interface InboxEnvelope {
@@ -30,6 +38,8 @@ export interface InboxEnvelope {
     countCap: number;
     proposalsAwaitingMe: InboxProposalRef[];
     truncatedProposals: number;
+    connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
+    truncatedConnectionRequests: number;
     humanAttention?: InboxHumanAttention;
 }
 export interface InboxAck {

package/dist/http/MarketplaceClient.d.ts

@@ -17,3 +17,10 @@ export interface PullOffersOptions {
 }
 export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare function claimOffer(agreementId: string, creds: Creds): Promise<Agreement>;
+export declare class MarketplaceClient {
+    private creds;
+    constructor(operatorKey: string, agentId: string);
+    publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
+    pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
+    claimOffer(agreementId: string): Promise<Agreement>;
+}

package/dist/http/MarketplaceClient.js

@@ -40,10 +40,15 @@ export async function publishOffer(payload, creds) {
 }
 export async function pullOffers(options, creds) {
     assertCreds(creds, 'marketplace offers pull');
-    const res = await fetch(`${getMarketplaceBaseUrl()}/offers/pull`, {
-        method: 'POST',
+    const params = new URLSearchParams();
+    if (options?.limit != null)
+        params.set('limit', String(options.limit));
+    if (options?.since)
+        params.set('since', options.since);
+    const qs = params.toString();
+    const res = await fetch(`${getMarketplaceBaseUrl()}/offers${qs ? `?${qs}` : ''}`, {
+        method: 'GET',
         headers: buildHeaders(creds),
-        body: JSON.stringify(options || {}),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
@@ -70,3 +75,16 @@ export async function claimOffer(agreementId, creds) {
         throw new Error(data?.['error'] || 'Claim failed');
     return data['offer'];
 }
+export class MarketplaceClient {
+    creds;
+    constructor(operatorKey, agentId) {
+        if (!operatorKey)
+            throw new Error('MarketplaceClient: operatorKey is required');
+        if (!agentId)
+            throw new Error('MarketplaceClient: agentId is required');
+        this.creds = { operatorKey, agentId };
+    }
+    publishOffer(payload) { return publishOffer(payload, this.creds); }
+    pullOffers(options) { return pullOffers(options, this.creds); }
+    claimOffer(agreementId) { return claimOffer(agreementId, this.creds); }
+}

package/dist/http/TaskClient.js

@@ -224,10 +224,15 @@ export async function publishToLedger(payload, creds) {
 }
 export async function pullFromLedger(options, creds) {
     assertCreds(creds, 'quest pull');
-    const res = await fetch(`${getMarketplaceBaseUrl()}/quests/pull`, {
-        method: 'POST',
+    const params = new URLSearchParams();
+    if (options?.limit != null)
+        params.set('limit', String(options.limit));
+    if (options?.since)
+        params.set('since', options.since);
+    const qs = params.toString();
+    const res = await fetch(`${getMarketplaceBaseUrl()}/quests${qs ? `?${qs}` : ''}`, {
+        method: 'GET',
         headers: buildHeaders(creds),
-        body: JSON.stringify(options || {}),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');

package/dist/http/index.d.ts

@@ -17,4 +17,4 @@ export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, Cont
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';
+export type { InboxScopeKind, InboxScopeEntry, InboxProposalRef, InboxConnectionRequestRef, InboxEnvelope, InboxAck, InboxAckResult, } from './InboxClient.js';

package/dist/types.d.ts

@@ -40,8 +40,16 @@ export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'countered' |
 export declare const AGREEMENT_ENGAGEMENT_KIND: {
     readonly HIRE: "hire";
     readonly SERVICE: "service";
+    /** ZIG-481: a bilateral reach link between two agents (no money, no work). */
+    readonly LINK: "link";
 };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
+export interface AgreementApprovalEntry {
+    partyId: string;
+    role?: string;
+    status?: string;
+    respondedAt?: string | null;
+}
 export interface Agreement {
     agreementId: string;
     description?: string;
@@ -54,7 +62,9 @@ export interface Agreement {
         payer?: string;
         creator?: string;
         creatorAgent?: string;
+        providerAgent?: string;
     };
+    approvals?: AgreementApprovalEntry[];
     /** Legacy root-level price — always null in practice. Use money.price instead. */
     price?: number | null;
     /** Price and payment state. price is in cents (e.g. 6000 = 6000 KRW). */

package/dist/types.js

@@ -12,6 +12,8 @@ export class ApiError extends Error {
 export const AGREEMENT_ENGAGEMENT_KIND = {
     HIRE: 'hire',
     SERVICE: 'service',
+    /** ZIG-481: a bilateral reach link between two agents (no money, no work). */
+    LINK: 'link',
 };
 /** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts ENTRY_TYPE */
 export const EntryTypes = {

package/package.json

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