@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/server/tools/tier2/connectionTools.ts

@@ -0,0 +1,75 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsConnectClient } from '../../ziggsconnect/ZiggsConnectClient.js';
+
+type Ctx = Record<string, unknown>;
+type AnyObj = Record<string, unknown>;
+
+interface ConnectError extends Error {
+  status?: number;
+  body?: string;
+}
+
+function clientFor(ctx: Ctx): ZiggsConnectClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsConnectClient({
+    operatorKey,
+    actAsAgentId: (ctx?.['agentId'] as string) || undefined,
+  });
+}
+
+function rethrowWithContext(error: unknown, prefix: string): never {
+  const e = error as ConnectError;
+  const wrapped = new Error(`${prefix}: ${e.message}`) as ConnectError;
+  if (e.status !== undefined) wrapped.status = e.status;
+  if (e.body !== undefined) wrapped.body = e.body;
+  (wrapped as unknown as AnyObj)['cause'] = error;
+  throw wrapped;
+}
+
+export const connectionProxyTool: ToolDefinition = defineTool(
+  'connection_proxy',
+  {
+    connectionId: { type: 'string', required: true },
+    grantId: { type: 'string', required: true },
+    action: { type: 'string', required: true },
+    payload: { type: 'object' },
+  },
+  async (args, ctx) => {
+    if (!args['connectionId']) throw new Error('connectionId is required');
+    if (!args['grantId']) throw new Error('grantId is required');
+    if (!args['action']) throw new Error('action is required');
+    try {
+      const result = await clientFor(ctx as Ctx).proxy({
+        connectionId: args['connectionId'] as string,
+        grantId: args['grantId'] as string,
+        action: args['action'] as string,
+        payload: args['payload'],
+      });
+      return { status: 'ok', result };
+    } catch (e) {
+      rethrowWithContext(e, 'Connection proxy failed');
+    }
+  },
+);
+
+export const connectionListGrantsTool: ToolDefinition = defineTool(
+  'connection_list_grants',
+  { connectionId: { type: 'string', required: true } },
+  async (args, ctx) => {
+    if (!args['connectionId']) throw new Error('connectionId is required');
+    try {
+      const grants = await clientFor(ctx as Ctx).listGrants({
+        connectionId: args['connectionId'] as string,
+      });
+      return { grants: grants || [] };
+    } catch (e) {
+      rethrowWithContext(e, 'Failed to list connection grants');
+    }
+  },
+);
+
+export const CONNECTION_TOOLS: ToolDefinition[] = [
+  connectionProxyTool,
+  connectionListGrantsTool,
+];

package/src/server/tools/tier2/contextTools.ts

@@ -0,0 +1,74 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsContextClient } from '../../ziggscontext/ZiggsContextClient.js';
+
+type Ctx = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): ZiggsContextClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsContextClient({
+    operatorKey,
+    actAsAgentId: (ctx?.['agentId'] as string) || undefined,
+  });
+}
+
+export const contextDiscoverTool: ToolDefinition = defineTool(
+  'context_discover',
+  {},
+  async (_args, ctx) => clientFor(ctx as Ctx).discover(),
+  {
+    description:
+      'List which chats, agreements, and org scopes this agent can reach via context grants (descriptors only — no message or artifact content).',
+  },
+);
+
+export const contextListGrantsTool: ToolDefinition = defineTool(
+  'context_list_grants',
+  {},
+  async (_args, ctx) => clientFor(ctx as Ctx).listGrants(),
+  {
+    description:
+      'List context grants held by this agent (grant ids and bounds). Does not fetch scoped content.',
+  },
+);
+
+export const contextDelegateTool: ToolDefinition = defineTool(
+  'context_delegate',
+  {
+    parentGrantId: { type: 'string', required: true },
+    holderId: { type: 'string', required: true },
+    scopeKind: { type: 'string', required: true },
+    scopeId: { type: 'string', required: true },
+    temporal: { type: 'string', required: true },
+    expiresAt: 'string',
+    watermarkAt: 'string',
+  },
+  async (args, ctx) => {
+    const temporal = args['temporal'] as string;
+    if (temporal !== 'from-now' && temporal !== 'from-start') {
+      throw new Error('temporal must be from-now or from-start');
+    }
+    const scopeKind = args['scopeKind'] as string;
+    if (scopeKind !== 'chat' && scopeKind !== 'agreement' && scopeKind !== 'org') {
+      throw new Error('scopeKind must be chat, agreement, or org');
+    }
+    return clientFor(ctx as Ctx).delegate({
+      parentGrantId: args['parentGrantId'] as string,
+      holderId: args['holderId'] as string,
+      scope: { kind: scopeKind as 'chat' | 'agreement' | 'org', id: args['scopeId'] as string },
+      temporal,
+      expiresAt: (args['expiresAt'] as string | undefined) ?? undefined,
+      watermarkAt: args['watermarkAt'] as string | undefined,
+    });
+  },
+  {
+    description:
+      'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only.',
+  },
+);
+
+export const CONTEXT_TOOLS = [
+  contextDiscoverTool,
+  contextListGrantsTool,
+  contextDelegateTool,
+] as const;

package/src/server/tools/tier2/discoveryTools.ts

@@ -0,0 +1,34 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { AgentSearchClient } from '@ziggs-ai/api-client';
+
+type Ctx = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): AgentSearchClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  const agentId = ctx?.['agentId'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  if (!agentId) throw new Error('agentId missing from tool context');
+  return new AgentSearchClient(operatorKey, agentId);
+}
+
+export const agentSearchTool: ToolDefinition = defineTool('agent_search',
+  { query: { type: 'string', required: true }, limit: 'number' },
+  async (args, ctx) => {
+    if (!args['query']) throw new Error('query is required');
+    const options: { limit?: number } = {};
+    if (typeof args['limit'] === 'number') options.limit = args['limit'] as number;
+    return clientFor(ctx as Ctx).searchAgents(args['query'] as string, options);
+  },
+  { description: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. Use before agreement_propose or agreement_subcontract to discover the right agent for a job.', isGenericFallback: true },
+);
+
+export const agentGetTool: ToolDefinition = defineTool('agent_get',
+  { agentId: { type: 'string', required: true } },
+  async (args, ctx) => {
+    if (!args['agentId']) throw new Error('agentId is required');
+    return clientFor(ctx as Ctx).getAgentById(args['agentId'] as string);
+  },
+  { description: 'Fetch the full profile of a specific agent by ID. Use to confirm capabilities and terms before proposing an agreement.' },
+);
+
+export const DISCOVERY_TOOLS: ToolDefinition[] = [agentSearchTool, agentGetTool];

package/src/server/tools/tier2/marketplaceTools.ts

@@ -0,0 +1,25 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { pullFromLedger } from '@ziggs-ai/api-client';
+
+type Ctx = Record<string, unknown>;
+
+// Read-only marketplace access. Publishing an open quest is NOT here: it is the
+// tier-1 protocol verb agreement_propose({ proposedTo: "everyone" }).
+export const marketplaceViewTool: ToolDefinition = defineTool('marketplace_view',
+  { limit: 'number', since: 'string' },
+  async (args, ctx) => {
+    const operatorKey = (ctx as Ctx)?.['operatorKey'] as string | undefined;
+    const agentId = (ctx as Ctx)?.['agentId'] as string | undefined;
+    if (!operatorKey) throw new Error('operatorKey missing from tool context');
+    if (!agentId) throw new Error('agentId missing from tool context');
+    const options: { limit?: number; since?: string } = {
+      limit: typeof args['limit'] === 'number' ? args['limit'] as number : 20,
+    };
+    if (args['since']) options.since = args['since'] as string;
+    const quests = await pullFromLedger(options, { operatorKey, agentId });
+    return { quests, count: quests.length };
+  },
+  { description: 'Browse open quests on the marketplace — work that buyers have broadcast to any willing agent. Use to find available jobs. To claim a quest, use agreement_respond on the returned agreementId. To publish your own quest, use agreement_propose({ proposedTo: "everyone" }).' },
+);
+
+export const MARKETPLACE_TOOLS: ToolDefinition[] = [marketplaceViewTool];

package/src/server/tools/tier2/paymentTools.ts

@@ -0,0 +1,193 @@
+import { defineTool, type ToolDefinition } from '../../../tools/defineTool.js';
+import { ZiggsPayClient } from '../../ziggspay/ZiggsPayClient.js';
+
+type Ctx = Record<string, unknown>;
+type AnyObj = Record<string, unknown>;
+
+function clientFor(ctx: Ctx): ZiggsPayClient {
+  const operatorKey = ctx?.['operatorKey'] as string | undefined;
+  if (!operatorKey) throw new Error('operatorKey missing from tool context');
+  return new ZiggsPayClient({ operatorKey, actAsAgentId: (ctx?.['agentId'] as string) || undefined });
+}
+
+interface PayError extends Error { status?: number; body?: string; }
+
+function rethrowWithContext(error: unknown, prefix: string): never {
+  const e = error as PayError;
+  const wrapped = new Error(`${prefix}: ${e.message}`) as PayError;
+  if (e.status !== undefined) wrapped.status = e.status;
+  if (e.body !== undefined) wrapped.body = e.body;
+  (wrapped as unknown as AnyObj)['cause'] = error;
+  throw wrapped;
+}
+
+function buildCaveats(args: AnyObj): AnyObj[] {
+  const caveats: AnyObj[] = [];
+  if (args['maxAmount'] != null) caveats.push({ type: 'max_amount', value: args['maxAmount'] });
+  if (args['dailyBudget'] != null) caveats.push({ type: 'daily_budget', value: args['dailyBudget'] });
+  if (args['allowedRecipients'] != null) caveats.push({ type: 'allowed_recipients', value: args['allowedRecipients'] });
+  if (args['expiresInSeconds'] != null) caveats.push({ type: 'expires_at', value: Date.now() + (args['expiresInSeconds'] as number) * 1000 });
+  return caveats;
+}
+
+export const paymentBalanceTool: ToolDefinition = defineTool('payment_balance', {},
+  async (_args, ctx) => {
+    try { return await clientFor(ctx as Ctx).balance(); }
+    catch (e) { rethrowWithContext(e, 'Failed to get balance'); }
+  },
+  { description: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds." },
+);
+
+export const paymentTransferTool: ToolDefinition = defineTool('payment_transfer',
+  { toWalletId: { type: 'string', required: true }, amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string', paymentGrantId: 'string' },
+  async (args, ctx) => {
+    if (!args['toWalletId']) throw new Error('toWalletId is required');
+    if (!args['amount'] || (args['amount'] as number) <= 0) throw new Error('amount must be positive');
+    const client = clientFor(ctx as Ctx);
+    let result: AnyObj;
+    try {
+      result = await client.transfer({ to: args['toWalletId'] as string, amount: Math.round(args['amount'] as number), description: (args['description'] as string) || 'Agent-initiated transfer', idempotencyKey: args['idempotencyKey'] as string | undefined, paymentGrantId: args['paymentGrantId'] as string | undefined }) as AnyObj;
+    } catch (e) { rethrowWithContext(e, 'Transfer failed'); }
+    if (result!['status'] === 'approval_required') {
+      return { status: 'approval_required', approvalId: result!['approvalId'] || null, expiresAt: result!['expiresAt'] || null, reason: result!['reason'] || null, amount: args['amount'], toWalletId: result!['toWalletId'],
+        message: 'Transfer paused: the wallet owner must approve this amount.',
+        next_actions: [{ tool: 'payment_wait_for_approval', when: 'You expect a quick decision (≤2 min) and can wait inline.', args: { approvalId: result!['approvalId'], timeoutMs: 120000 } }, { tool: 'task_update_plan_step', when: 'You want to abandon the transfer and route around it.' }] };
+    }
+    return { status: 'transferred', transactionId: result!['transactionId'] || null, amount: args['amount'], toWalletId: result!['toWalletId'] };
+  },
+);
+
+export const paymentWaitForApprovalTool: ToolDefinition = defineTool('payment_wait_for_approval',
+  { approvalId: { type: 'string', required: true }, timeoutMs: 'number', pollMs: 'number' },
+  async (args, ctx) => {
+    if (!args['approvalId']) throw new Error('approvalId is required');
+    try {
+      const result = await clientFor(ctx as Ctx).waitForApproval(args['approvalId'] as string, { timeoutMs: args['timeoutMs'] as number | undefined, pollMs: args['pollMs'] as number | undefined }) as AnyObj;
+      return { status: result['status'], approvalId: args['approvalId'], transactionId: result['transactionId'] || null, approval: result['approval'] || null };
+    } catch (e) { rethrowWithContext(e, 'wait_for_approval failed'); }
+  },
+);
+
+export const paymentResolveWalletTool: ToolDefinition = defineTool('payment_resolve_wallet',
+  { userId: 'string', agentId: 'string' },
+  async (args, ctx) => {
+    if (!args['userId'] && !args['agentId']) throw new Error('Provide userId or agentId to resolve a wallet');
+    try {
+      const wallet = await clientFor(ctx as Ctx).resolve({ userId: args['userId'] as string | undefined, agentId: args['agentId'] as string | undefined }) as AnyObj | null;
+      return { walletId: wallet?.['walletId'] || null, ownerId: wallet?.['ownerId'] || null, currency: wallet?.['currency'] || 'pez', status: wallet?.['status'] || null };
+    } catch (e) { rethrowWithContext(e, 'Failed to resolve wallet'); }
+  },
+  { description: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.' },
+);
+
+export const paymentHoldTool: ToolDefinition = defineTool('payment_hold',
+  { amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string' },
+  async (args, ctx) => {
+    if (!args['amount'] || (args['amount'] as number) <= 0) throw new Error('amount must be positive');
+    try {
+      const result = await clientFor(ctx as Ctx).hold({ amount: Math.round(args['amount'] as number), description: (args['description'] as string) || 'Agent escrow hold', idempotencyKey: args['idempotencyKey'] as string | undefined }) as AnyObj;
+      return { status: 'held', transactionId: (result['transaction'] as AnyObj | undefined)?.['transactionId'] || null, amount: args['amount'] };
+    } catch (e) { rethrowWithContext(e, 'Hold failed'); }
+  },
+  { description: 'Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with payment_release once work is complete or to refund if work is cancelled.' },
+);
+
+export const paymentReleaseTool: ToolDefinition = defineTool('payment_release',
+  { holdId: { type: 'string', required: true }, action: { type: 'string', required: true }, toWalletId: 'string', idempotencyKey: 'string' },
+  async (args, ctx) => {
+    if (!args['holdId']) throw new Error('holdId is required');
+    if (args['action'] !== 'complete' && args['action'] !== 'refund') throw new Error("action must be 'complete' or 'refund'");
+    if (args['action'] === 'complete' && !args['toWalletId']) throw new Error('toWalletId is required when action=complete');
+    try {
+      const result = await clientFor(ctx as Ctx).release({ holdId: args['holdId'] as string, action: args['action'] as string, toWalletId: args['toWalletId'] as string | undefined, idempotencyKey: args['idempotencyKey'] as string | undefined }) as AnyObj;
+      return { status: args['action'] === 'complete' ? 'settled' : 'refunded', transactionId: (result['transaction'] as AnyObj | undefined)?.['transactionId'] || null, holdId: args['holdId'], action: args['action'] };
+    } catch (e) { rethrowWithContext(e, 'Release failed'); }
+  },
+  { description: "Settle or refund an escrow hold. Use action='complete' to transfer held funds to toWalletId (work done), or action='refund' to return funds to the sender (work cancelled)." },
+);
+
+const issueGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  if (!args['holderId']) throw new Error('holderId is required');
+  try {
+    const caveats = buildCaveats(args);
+    const result = await clientFor(ctx).issueGrant({ holderId: args['holderId'] as string, caveats }) as AnyObj;
+    const grant = result['grant'] as AnyObj | undefined;
+    return { grantId: grant?.['grantId'] || null, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
+  } catch (e) { rethrowWithContext(e, 'Failed to issue payment grant'); }
+};
+
+export const paymentIssueGrantTool: ToolDefinition = defineTool('payment_issue_grant',
+  { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  issueGrantHandler,
+);
+
+/** @deprecated Use payment_issue_grant */
+export const paymentIssueTokenTool: ToolDefinition = defineTool('payment_issue_token',
+  { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  issueGrantHandler,
+);
+
+const attenuateGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  const grantId = (args['grantId'] || args['tokenId']) as string;
+  if (!grantId) throw new Error('grantId is required');
+  if (!args['holderId']) throw new Error('holderId is required');
+  try {
+    const caveats = buildCaveats(args);
+    const result = await clientFor(ctx).attenuateGrant({ grantId, holderId: args['holderId'] as string, caveats }) as AnyObj;
+    const grant = result['grant'] as AnyObj | undefined;
+    return { grantId: grant?.['grantId'] || null, parentGrantId: grant?.['parentGrantId'] || grantId, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
+  } catch (e) { rethrowWithContext(e, 'Failed to attenuate payment grant'); }
+};
+
+export const paymentAttenuateGrantTool: ToolDefinition = defineTool('payment_attenuate_grant',
+  { grantId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  attenuateGrantHandler,
+);
+
+/** @deprecated Use payment_attenuate_grant */
+export const paymentAttenuateTokenTool: ToolDefinition = defineTool('payment_attenuate_token',
+  { tokenId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
+  attenuateGrantHandler,
+);
+
+const revokeGrantHandler = async (args: AnyObj, ctx: Ctx) => {
+  const grantId = (args['grantId'] || args['tokenId']) as string;
+  if (!grantId) throw new Error('grantId is required');
+  try {
+    const result = await clientFor(ctx).revokeGrant(grantId) as AnyObj;
+    return { status: 'revoked', grantId, revoked: result['revoked'] ?? null };
+  } catch (e) { rethrowWithContext(e, 'Failed to revoke payment grant'); }
+};
+
+export const paymentRevokeGrantTool: ToolDefinition = defineTool('payment_revoke_grant',
+  { grantId: { type: 'string', required: true } },
+  revokeGrantHandler,
+);
+
+/** @deprecated Use payment_revoke_grant */
+export const paymentRevokeTokenTool: ToolDefinition = defineTool('payment_revoke_token',
+  { tokenId: { type: 'string', required: true } },
+  revokeGrantHandler,
+);
+
+const listGrantsHandler = async (_args: AnyObj, ctx: Ctx) => {
+  try {
+    const result = await clientFor(ctx).listGrants();
+    return { grants: result || [] };
+  } catch (e) { rethrowWithContext(e, 'Failed to list payment grants'); }
+};
+
+export const paymentListGrantsTool: ToolDefinition = defineTool('payment_list_grants', {},
+  listGrantsHandler,
+);
+
+/** @deprecated Use payment_list_grants */
+export const paymentListTokensTool: ToolDefinition = defineTool('payment_list_tokens', {},
+  listGrantsHandler,
+);
+
+export const PAYMENT_TOOLS: ToolDefinition[] = [
+  paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
+  paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
+  paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool,
+];

package/src/server/ziggsconnect/ZiggsConnectClient.ts

@@ -0,0 +1,126 @@
+import 'dotenv/config';
+
+function getDefaultBaseUrl(): string {
+  return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+
+function parseError(text: string, fallback: string): string {
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    return (parsed['message'] as string) || (parsed['error'] as string) || text;
+  } catch {
+    return text;
+  }
+}
+
+interface ConnectError extends Error {
+  status?: number;
+  body?: string;
+}
+
+export interface ZiggsConnectClientOptions {
+  operatorKey: string;
+  actAsAgentId?: string;
+  baseUrl?: string;
+}
+
+export interface ProxyParams {
+  connectionId: string;
+  grantId: string;
+  action: string;
+  payload?: unknown;
+}
+
+export class ZiggsConnectClient {
+  private operatorKey: string;
+  private actAsAgentId: string | null;
+  private baseUrl: string;
+
+  constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsConnectClientOptions) {
+    if (!operatorKey || typeof operatorKey !== 'string') {
+      throw new Error('ZiggsConnectClient requires an operatorKey');
+    }
+    this.operatorKey = operatorKey;
+    this.actAsAgentId = actAsAgentId || null;
+    this.baseUrl = baseUrl || getDefaultBaseUrl();
+  }
+
+  /**
+   * Present a ConnectionGrant to the broker and perform a provider action.
+   * Returns the provider result — never the raw OAuth token.
+   */
+  async proxy({ connectionId, grantId, action, payload }: ProxyParams): Promise<unknown> {
+    if (!connectionId) throw new Error('proxy: connectionId is required');
+    if (!grantId) throw new Error('proxy: grantId is required');
+    if (!action) throw new Error('proxy: action is required');
+    if (!this.actAsAgentId) {
+      throw new Error(
+        'proxy: actAsAgentId is required — connection broker calls must impersonate the grant holder agent',
+      );
+    }
+    const res = (await this._post(`/connections/${encodeURIComponent(connectionId)}/proxy`, {
+      grantId,
+      action,
+      payload: payload ?? {},
+    })) as Record<string, unknown>;
+    return res['result'] ?? res;
+  }
+
+  /**
+   * List ConnectionGrants held by this agent for a connection.
+   * Requires actAsAgentId; filters server rows to holderId === agent.
+   */
+  async listGrants({ connectionId }: { connectionId: string }): Promise<unknown[]> {
+    if (!connectionId) throw new Error('listGrants: connectionId is required');
+    if (!this.actAsAgentId) {
+      throw new Error(
+        'listGrants: actAsAgentId is required — grants are scoped to the impersonated agent',
+      );
+    }
+    const res = (await this._get(
+      `/connections/${encodeURIComponent(connectionId)}/grants`,
+    )) as Record<string, unknown>;
+    const grants = (res['grants'] as Array<Record<string, unknown>>) || [];
+    return grants.filter((g) => g['holderId'] === this.actAsAgentId);
+  }
+
+  private _buildHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+    if (this.actAsAgentId) h['X-Agent-Id'] = this.actAsAgentId;
+    return h;
+  }
+
+  private async _request(method: string, path: string, body: unknown): Promise<unknown> {
+    const init: RequestInit = {
+      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}`)) as ConnectError;
+      err.status = response.status;
+      err.body = text;
+      throw err;
+    }
+    return text ? JSON.parse(text) : null;
+  }
+
+  private _get(path: string): Promise<unknown> {
+    return this._request('GET', path, undefined);
+  }
+
+  private _post(path: string, body: unknown): Promise<unknown> {
+    return this._request('POST', path, body ?? {});
+  }
+}
+
+export function createZiggsConnectClient(
+  opts: ZiggsConnectClientOptions,
+): ZiggsConnectClient {
+  return new ZiggsConnectClient(opts);
+}

package/src/server/ziggscontext/ZiggsContextClient.ts

@@ -0,0 +1,137 @@
+import 'dotenv/config';
+
+function getDefaultBaseUrl(): string {
+  return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+
+function parseError(text: string, fallback: string): string {
+  if (!text) return fallback;
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    return (parsed['message'] as string) || (parsed['error'] as string) || text;
+  } catch {
+    return text;
+  }
+}
+
+interface ContextError extends Error {
+  status?: number;
+  body?: string;
+}
+
+export interface ZiggsContextClientOptions {
+  operatorKey: string;
+  actAsAgentId?: string;
+  baseUrl?: string;
+}
+
+export interface ContextReachDescriptor {
+  grantId: string;
+  scope: { kind: 'chat' | 'agreement' | 'org'; id: string };
+  temporal: 'from-now' | 'from-start';
+  watermarkAt: string;
+  expiresAt: string | null;
+  parentGrantId: string | null;
+  createdAt: string;
+}
+
+export interface DelegateContextGrantParams {
+  parentGrantId: string;
+  holderId: string;
+  scope: { kind: 'chat' | 'agreement' | 'org'; id: string };
+  temporal: 'from-now' | 'from-start';
+  expiresAt?: string | null;
+  watermarkAt?: string;
+}
+
+/**
+ * HTTP client for context grants (ZIG-413).
+ * Presentation model (signed bytes vs grant id) is intentionally not baked in here.
+ */
+export class ZiggsContextClient {
+  private operatorKey: string;
+  private actAsAgentId: string | null;
+  private baseUrl: string;
+
+  constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsContextClientOptions) {
+    if (!operatorKey || typeof operatorKey !== 'string') {
+      throw new Error('ZiggsContextClient requires an operatorKey');
+    }
+    this.operatorKey = operatorKey;
+    this.actAsAgentId = actAsAgentId || null;
+    this.baseUrl = baseUrl || getDefaultBaseUrl();
+  }
+
+  /** ZIG-412: scope descriptors for what this agent can reach (no content). */
+  async discover(): Promise<ContextReachDescriptor[]> {
+    this.requireActAsAgent('discover');
+    const res = (await this._get('/context/discovery')) as Record<string, unknown>;
+    return (res['reach'] as ContextReachDescriptor[]) || [];
+  }
+
+  /** List persisted grant rows held by this agent (may include signedBytes). */
+  async listGrants(): Promise<unknown[]> {
+    this.requireActAsAgent('listGrants');
+    const res = (await this._get('/context/grants')) as Record<string, unknown>;
+    const grants = (res['grants'] as Array<Record<string, unknown>>) || [];
+    return grants.filter((g) => g['holderId'] === this.actAsAgentId);
+  }
+
+  /** Holder delegates a narrower child grant. */
+  async delegate(params: DelegateContextGrantParams): Promise<unknown> {
+    this.requireActAsAgent('delegate');
+    if (!params.parentGrantId) throw new Error('delegate: parentGrantId is required');
+    if (!params.holderId) throw new Error('delegate: holderId is required');
+    if (!params.scope?.kind || !params.scope?.id) {
+      throw new Error('delegate: scope { kind, id } is required');
+    }
+    return this._post(`/context/grants/${encodeURIComponent(params.parentGrantId)}/delegate`, {
+      holderId: params.holderId,
+      scope: params.scope,
+      temporal: params.temporal,
+      expiresAt: params.expiresAt,
+      watermarkAt: params.watermarkAt,
+    });
+  }
+
+  private requireActAsAgent(method: string): void {
+    if (!this.actAsAgentId) {
+      throw new Error(
+        `${method}: actAsAgentId is required — context grant calls must impersonate the grant holder agent`,
+      );
+    }
+  }
+
+  private _buildHeaders(extra: Record<string, string> = {}): Record<string, string> {
+    const h: Record<string, string> = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+    if (this.actAsAgentId) h['X-Agent-Id'] = this.actAsAgentId;
+    return h;
+  }
+
+  private async _request(method: string, path: string, body: unknown): Promise<unknown> {
+    const init: RequestInit = {
+      method,
+      headers: this._buildHeaders(
+        body !== undefined ? { 'content-type': 'application/json' } : {},
+      ),
+    };
+    if (body !== undefined) init.body = JSON.stringify(body);
+    const res = await fetch(`${this.baseUrl}${path}`, init);
+    const text = await res.text();
+    if (!res.ok) {
+      const err = new Error(parseError(text, `${method} ${path} failed (${res.status})`)) as ContextError;
+      err.status = res.status;
+      err.body = text;
+      throw err;
+    }
+    return text ? JSON.parse(text) : {};
+  }
+
+  private _get(path: string): Promise<unknown> {
+    return this._request('GET', path, undefined);
+  }
+
+  private _post(path: string, body: unknown): Promise<unknown> {
+    return this._request('POST', path, body);
+  }
+}