@ziggs-ai/api-client 0.1.3 → 0.1.5

package/src/http/AgreementClient.ts

@@ -0,0 +1,721 @@
+import 'dotenv/config';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { type Creds, type Agreement, type EngagementKind, OPEN_AGREEMENT_TARGET, ApiError } from '../types.js';
+import { publishToLedger, type PublishToLedgerPayload } from './TaskClient.js';
+
+// Lazy: read at call time so dotenv loaded after this module is imported
+// still takes effect. Baking it at module-load time would freeze the URL
+// before the caller's dotenv.config() runs.
+function getAgreementBaseUrl(): string {
+  return `${getBackendUrl()}/agreements`;
+}
+
+function buildHeaders(creds: Creds): Record<string, string> {
+  return {
+    'content-type': 'application/json',
+    Authorization: `Bearer ${creds.operatorKey}`,
+    'X-Agent-Id': creds.agentId,
+  };
+}
+
+function assertCreds(creds: Creds | undefined | null, op: string): asserts creds is Creds {
+  if (!creds?.operatorKey) throw new Error(`operatorKey is required for ${op}`);
+  if (!creds?.agentId) throw new Error(`agentId is required for ${op}`);
+}
+
+function parseErrorMessage(responseBody: string, defaultMessage: string): string {
+  if (!responseBody) return defaultMessage;
+  try {
+    const d = JSON.parse(responseBody) as Record<string, unknown>;
+    return (d['details'] as string) || (d['error'] as string) || (d['message'] as string) || defaultMessage;
+  } catch {
+    return responseBody || defaultMessage;
+  }
+}
+
+function throwApiError(response: Response, responseBody: string, defaultMessage: string): never {
+  throw new ApiError(parseErrorMessage(responseBody, defaultMessage), response.status, responseBody);
+}
+
+// ---------------------------------------------------------------------------
+// Proposal lifecycle
+// ---------------------------------------------------------------------------
+
+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 async function proposeAgreement(
+  proposalData: ProposeDirectInput,
+  creds: Creds,
+): Promise<Agreement> {
+  if (!proposalData) throw new Error('Proposal data is required for proposal creation');
+  assertCreds(creds, 'proposal creation');
+
+  const { idempotencyKey, ...bodyData } = proposalData;
+  const headers = buildHeaders(creds);
+  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+
+  // ZIG-207: canonical REST path. Backend keeps /propose serving the
+  // identical handler with a Deprecation/Sunset header until PR-F removes it.
+  const res = await fetch(`${getAgreementBaseUrl()}/proposals`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(bodyData),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Proposal creation failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { agreement } from POST /agreements/proposals');
+  }
+  return data['agreement'] as Agreement;
+}
+
+/** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
+export async function proposeDirectTo(
+  input: ProposeDirectInput,
+  creds: Creds,
+): Promise<Agreement> {
+  return proposeAgreement(input, creds);
+}
+
+/** Propose an open quest (`proposedTo: "everyone"`). Server defaults `engagementKind` to `service`. */
+export async function proposeBroadcast(
+  input: ProposeBroadcastInput,
+  creds: Creds,
+): Promise<Agreement> {
+  return proposeAgreement({ ...input, proposedTo: OPEN_AGREEMENT_TARGET }, creds);
+}
+
+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 async function delegateAgreement(
+  proposalData: DelegateAgreementData,
+  creds: Creds,
+): Promise<Agreement> {
+  if (!proposalData) throw new Error('Proposal data is required for delegation');
+  if (!proposalData.parentAgreementId)
+    throw new Error('parentAgreementId is required for delegation');
+  assertCreds(creds, 'proposal creation');
+
+  const { idempotencyKey, parentAgreementId } = proposalData;
+  const headers = buildHeaders(creds);
+  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+
+  // ZIG-207 / ZIG-270: parentAgreementId in path AND body. Backend's
+  // `DelegateTaskDto` validates `parentAgreementId` as a required string;
+  // controller (`POST /agreements/:parentAgreementId/delegations`) merges
+  // path over body, so duplicating the value is harmless. Stripping it
+  // from the body (as ZIG-207 #72 did) trips DTO validation and returns
+  // `400: parentAgreementId must be a string` → infinite retry loop in
+  // `agreement_subcontract`. Send both, let the path win.
+  const bodyWithParent = { ...proposalData };
+  delete (bodyWithParent as { idempotencyKey?: string }).idempotencyKey;
+  const res = await fetch(
+    `${getAgreementBaseUrl()}/${encodeURIComponent(parentAgreementId)}/delegations`,
+    {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(bodyWithParent),
+    },
+  );
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Delegation failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { agreement } from POST /agreements/:parentAgreementId/delegations');
+  }
+  return data['agreement'] as Agreement;
+}
+
+export async function respondToAgreement(
+  agreementId: string,
+  action: 'approve' | 'reject',
+  creds: Creds,
+): Promise<Agreement> {
+  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',
+    headers: buildHeaders(creds),
+    body: JSON.stringify({ action }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Proposal response failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { agreement } from /agreements/:id/respond');
+  }
+  return data['agreement'] as 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 async function counterAgreement(
+  agreementId: string,
+  counter: CounterAgreementData,
+  creds: Creds,
+): Promise<Agreement> {
+  if (!agreementId) throw new Error('agreementId is required for counter-offer');
+  assertCreds(creds, 'counter proposal');
+
+  const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/counter`, {
+    method: 'POST',
+    headers: buildHeaders(creds),
+    body: JSON.stringify(counter || {}),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Counter proposal failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { agreement } from /agreements/:id/counter');
+  }
+  return data['agreement'] as Agreement;
+}
+
+export async function getAgreementStatus(agreementId: string, creds: Creds): Promise<unknown | null> {
+  if (!agreementId) return null;
+  assertCreds(creds, 'proposal status read');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/status`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Proposal status read failed: ${res.status} ${res.statusText} ${body}`);
+      return null;
+    }
+    return await res.json().catch(() => null);
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Proposal status read failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+export interface ListAgreementsFilters {
+  status?: string;
+  engagementKind?: EngagementKind;
+  proposalStatus?: string;
+  hasTask?: boolean;
+}
+
+export async function listAgreements(filters: ListAgreementsFilters = {}, creds: Creds): Promise<Agreement[]> {
+  assertCreds(creds, 'list agreements');
+
+  try {
+    // Canonical query path: GET /agreements?scope=&status=&engagementKind=&...
+    const url = new URL(getAgreementBaseUrl());
+    if (filters.status) url.searchParams.set('status', filters.status);
+    if (filters.engagementKind) url.searchParams.set('engagementKind', filters.engagementKind);
+    if (filters.proposalStatus) url.searchParams.set('proposalStatus', filters.proposalStatus);
+    if (filters.hasTask != null) url.searchParams.set('hasTask', String(filters.hasTask));
+
+    const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ List agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return Array.isArray(data?.['agreements']) ? (data['agreements'] as Agreement[]) : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ List agreements failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+export interface GetMyAgreementsFilters {
+  engagementKind?: EngagementKind;
+  proposalStatus?: string;
+  hasTask?: boolean;
+}
+
+export async function getMyAgreements(filters: GetMyAgreementsFilters = {}, creds: Creds): Promise<Agreement[]> {
+  assertCreds(creds, 'get my agreements');
+
+  try {
+    // Canonical query path: GET /agreements?scope=mine returns the enriched
+    // shape (tasks + originChatId + isYou flags).
+    const url = new URL(getAgreementBaseUrl());
+    url.searchParams.set('scope', 'mine');
+    if (filters.engagementKind) url.searchParams.set('engagementKind', filters.engagementKind);
+    if (filters.proposalStatus) url.searchParams.set('proposalStatus', filters.proposalStatus);
+    if (filters.hasTask != null) url.searchParams.set('hasTask', String(filters.hasTask));
+
+    const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get my agreements failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return Array.isArray(data?.['agreements']) ? (data['agreements'] as Agreement[]) : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get my agreements failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+export async function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null> {
+  if (!agreementId) return null;
+  assertCreds(creds, 'get agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return null;
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return (data?.['agreement'] as Agreement) ?? null;
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get agreement failed: ${(e as Error).message}`);
+    return 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 async function createAgreement(
+  body: CreateAgreementBody,
+  creds: Creds,
+): Promise<{ ok: boolean; agreement: Agreement }> {
+  if (!body) throw new Error('Body is required for agreement creation');
+  assertCreds(creds, 'agreement creation');
+
+  // Canonical REST create: POST /agreements.
+  const res = await fetch(getAgreementBaseUrl(), {
+    method: 'POST',
+    headers: buildHeaders(creds),
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const responseBody = await res.text().catch(() => '');
+    throwApiError(res, responseBody, `Agreement creation failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { ok, agreement } from POST /agreements');
+  }
+  return data as unknown as { ok: boolean; agreement: Agreement };
+}
+
+export async function revokeAgreement(
+  agreementId: string,
+  creds: Creds,
+): Promise<{ ok: boolean; agreement: Agreement }> {
+  if (!agreementId) throw new Error('agreementId is required for revocation');
+  assertCreds(creds, 'agreement revocation');
+
+  // ZIG-207: canonical REST verb. Legacy POST /agreements/:id/revoke stays
+  // serving the identical handler (with Deprecation headers) until PR-F.
+  const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}`, {
+    method: 'DELETE',
+    headers: buildHeaders(creds),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Agreement revocation failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['agreement']) {
+    throw new Error('Invalid response: expected { ok, agreement } from DELETE /agreements/:id');
+  }
+  return data as unknown as { ok: boolean; agreement: Agreement };
+}
+
+// ---------------------------------------------------------------------------
+// Chat links
+// ---------------------------------------------------------------------------
+
+export async function getAgreementsByChat(chatId: string, creds: Creds): Promise<unknown[]> {
+  if (!chatId) return [];
+  assertCreds(creds, 'get agreements by chat');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/by-chat/${encodeURIComponent(chatId)}`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    const links = data?.['links'] ?? data?.['agreements'];
+    return Array.isArray(links) ? links : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+export type ChatLinkType = 'origin' | 'mention' | 'delegation' | 'join';
+
+export async function linkAgreementToChat(
+  agreementId: string,
+  chatId: string,
+  linkType: ChatLinkType = 'mention',
+  creds: Creds,
+): Promise<unknown | null> {
+  if (!agreementId || !chatId) return null;
+  assertCreds(creds, 'link agreement to chat');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/link`, {
+      method: 'POST',
+      headers: buildHeaders(creds),
+      body: JSON.stringify({ chatId, linkType }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return null;
+    }
+
+    return await res.json().catch(() => null);
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Link agreement to chat failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+export async function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]> {
+  if (!agreementId) return [];
+  assertCreds(creds, 'get chats for agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/chats`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return Array.isArray(data?.['links']) ? data['links'] : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get chats for agreement failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+export async function joinAgreement(
+  agreementId: string,
+  creds: Creds,
+): Promise<{ chatId: string; agentId: string | null; isNew: boolean }> {
+  if (!agreementId) throw new Error('agreementId is required for join');
+  assertCreds(creds, 'join agreement');
+
+  const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/join`, {
+    method: 'POST',
+    headers: buildHeaders(creds),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throwApiError(res, body, `Join agreement failed: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+  if (!data?.['chatId']) {
+    throw new Error('Invalid response: expected { chatId } from /agreements/:id/join');
+  }
+  return data as unknown as { chatId: string; agentId: string | null; isNew: boolean };
+}
+
+// ---------------------------------------------------------------------------
+// Artifact links
+// ---------------------------------------------------------------------------
+
+export type ArtifactLinkType = 'produced' | 'referenced';
+
+export async function linkArtifactToAgreement(
+  agreementId: string,
+  artifactId: string,
+  linkType: ArtifactLinkType = 'produced',
+  creds: Creds,
+): Promise<unknown | null> {
+  if (!agreementId || !artifactId) return null;
+  assertCreds(creds, 'link artifact to agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/artifacts`, {
+      method: 'POST',
+      headers: buildHeaders(creds),
+      body: JSON.stringify({ artifactId, linkType }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Link artifact failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return null;
+    }
+
+    return await res.json().catch(() => null);
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Link artifact failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+export async function getArtifactsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]> {
+  if (!agreementId) return [];
+  assertCreds(creds, 'get artifacts for agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/artifacts`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get artifacts failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return Array.isArray(data?.['artifacts']) ? data['artifacts'] : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get artifacts failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// User links
+// ---------------------------------------------------------------------------
+
+export type UserRole = 'payer' | 'provider' | 'participant' | 'observer';
+
+export async function linkUserToAgreement(
+  agreementId: string,
+  userId: string,
+  role: UserRole,
+  creds: Creds,
+): Promise<unknown | null> {
+  if (!agreementId || !userId || !role) return null;
+  assertCreds(creds, 'link user to agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
+      method: 'POST',
+      headers: buildHeaders(creds),
+      body: JSON.stringify({ userId, role }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return null;
+    }
+
+    return await res.json().catch(() => null);
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${(e as Error).message}`);
+    return null;
+  }
+}
+
+export async function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]> {
+  if (!agreementId) return [];
+  assertCreds(creds, 'get users for agreement');
+
+  try {
+    const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
+      method: 'GET',
+      headers: buildHeaders(creds),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
+      return [];
+    }
+
+    const data = await res.json().catch(() => null) as Record<string, unknown> | null;
+    return Array.isArray(data?.['users']) ? data['users'] : [];
+  } catch (e) {
+    runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Unified contract creation (legacy) — prefer proposeDirectTo / proposeBroadcast /
+// delegateAgreement / publishOpenQuest for clarity.
+// ---------------------------------------------------------------------------
+
+/** @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 async function createContract(
+  input: CreateContractInput,
+  creds: Creds,
+): Promise<Agreement> {
+  assertCreds(creds, 'contract creation');
+  const { kind, ...rest } = input;
+
+  if (kind === 'direct') return proposeDirectTo(rest as ProposeDirectInput, creds);
+  if (kind === 'delegate') return delegateAgreement(rest as DelegateAgreementData, creds);
+  return publishOpenQuest(rest as PublishToLedgerPayload, creds);
+}
+
+/** Publish a buyer-broadcast quest to the marketplace ledger (Store "Wanted"). */
+export async function publishOpenQuest(
+  payload: PublishToLedgerPayload,
+  creds: Creds,
+): Promise<Agreement> {
+  return publishToLedger(payload, creds);
+}