packages/persistence/src/hosted.ts · aryaamin/openclasp

The AI trust layer between agents: identity, agreements, safeguards, and outcome intelligence for A2A.

Viewing files at commit 132dee380109Commit details View latest

packages/persistence/src/hosted.ts 481 lines · 17.7 KB · typescript

import { neon, type NeonQueryFunction } from '@neondatabase/serverless';
import {
  DEFAULT_EXTENSION_URI,
  FederatedInteractionSchema,
  PublicAgentCardSchema,
  canonicalHash,
  type FederatedInteraction,
  type PublicAgentCard,
} from '../../protocol/src/index.js';
import type { AgentProfile } from './onboarding.js';

export type HostedRecordKind =
  | 'agent'
  | 'delegation'
  | 'contract'
  | 'interaction'
  | 'event'
  | 'receipt'
  | 'feedback'
  | 'conflict'
  | 'profile'
  | 'consent'
  | 'revocation'
  | 'project'
  | 'agent_profile'
  | 'installation'
  | 'setup_request'
  | 'publication';

export type { PublicAgentCard, FederatedInteraction } from '../../protocol/src/index.js';

function normalizePublicAgentCard(value: unknown): PublicAgentCard {
  const current = PublicAgentCardSchema.safeParse(value);
  if (current.success) return current.data;
  const legacy = value as Record<string, unknown>;
  const agentId = String(legacy.agentId ?? '');
  const baseUrl = (process.env.OPENCLASP_PUBLIC_URL ?? 'https://openclasp.vercel.app').replace(
    /\/$/,
    '',
  );
  return PublicAgentCardSchema.parse({
    protocolVersion: '0.1',
    agentId,
    name: legacy.name,
    description: '',
    framework: legacy.framework,
    agentVersion: '1.0.0',
    capabilities: legacy.capabilities,
    limitations: legacy.limitations,
    assurance: legacy.assurance,
    transports: [],
    cardUrl: `${baseUrl}/agents/${encodeURIComponent(agentId)}/card.json`,
    a2aAgentCardUrl: `${baseUrl}/agents/${encodeURIComponent(agentId)}/a2a-agent-card.json`,
    extensionUri: DEFAULT_EXTENSION_URI,
    publishedAt: legacy.publishedAt,
    updatedAt: legacy.updatedAt,
  });
}

export function buildPublicAgentCard(
  agent: AgentProfile,
  baseUrl: string,
  previous?: PublicAgentCard,
): PublicAgentCard {
  const now = new Date().toISOString();
  const root = baseUrl.replace(/\/$/, '');
  return PublicAgentCardSchema.parse({
    protocolVersion: '0.1',
    agentId: agent.agentId,
    name: agent.name,
    description: agent.description ?? '',
    framework: agent.framework,
    agentVersion: agent.agentVersion ?? '1.0.0',
    capabilities: agent.capabilities,
    limitations: agent.limitations,
    assurance: 'oauth_authenticated',
    transports: agent.a2aEndpoint
      ? [{ protocol: 'A2A/1.0', protocolBinding: 'JSONRPC', endpoint: agent.a2aEndpoint }]
      : [],
    cardUrl: `${root}/agents/${encodeURIComponent(agent.agentId)}/card.json`,
    a2aAgentCardUrl: `${root}/agents/${encodeURIComponent(agent.agentId)}/a2a-agent-card.json`,
    extensionUri: DEFAULT_EXTENSION_URI,
    publishedAt: previous?.publishedAt ?? now,
    updatedAt: now,
  });
}

export type AccountSettings = {
  displayName: string;
  contributionEnabled: boolean;
  retentionDays: number;
  evidenceSharing: 'never' | 'ask' | 'contract_only';
  rawConversationsStored: false;
};

const defaults: AccountSettings = {
  displayName: '',
  contributionEnabled: false,
  retentionDays: 30,
  evidenceSharing: 'ask',
  rawConversationsStored: false,
};

export class HostedRepository {
  private readonly sql: NeonQueryFunction<false, false>;
  private initialized?: Promise<void>;

  constructor(databaseUrl: string) {
    this.sql = neon(databaseUrl);
  }

  ensureSchema(): Promise<void> {
    return (this.initialized ??= (async () => {
      await this.sql`
        CREATE TABLE IF NOT EXISTS openclasp_records (
          operator_id TEXT NOT NULL,
          kind TEXT NOT NULL,
          record_id TEXT NOT NULL,
          payload JSONB NOT NULL,
          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
          PRIMARY KEY (operator_id, kind, record_id)
        )
      `;
      await this.sql`
        CREATE INDEX IF NOT EXISTS openclasp_records_operator_created
        ON openclasp_records(operator_id, created_at DESC)
      `;
      await this.sql`
        CREATE TABLE IF NOT EXISTS openclasp_account_settings (
          operator_id TEXT PRIMARY KEY,
          display_name TEXT NOT NULL DEFAULT '',
          contribution_enabled BOOLEAN NOT NULL DEFAULT FALSE,
          retention_days INTEGER NOT NULL DEFAULT 30 CHECK (retention_days BETWEEN 0 AND 3650),
          evidence_sharing TEXT NOT NULL DEFAULT 'ask'
            CHECK (evidence_sharing IN ('never', 'ask', 'contract_only')),
          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
        )
      `;
      await this.sql`
        CREATE TABLE IF NOT EXISTS openclasp_public_agents (
          agent_id TEXT PRIMARY KEY,
          operator_id TEXT NOT NULL,
          card JSONB NOT NULL,
          published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
        )
      `;
      await this.sql`
        CREATE INDEX IF NOT EXISTS openclasp_public_agents_updated
        ON openclasp_public_agents(updated_at DESC)
      `;
      await this.sql`
        CREATE TABLE IF NOT EXISTS openclasp_federated_interactions (
          interaction_id TEXT PRIMARY KEY,
          initiator_operator_id TEXT NOT NULL,
          responder_operator_id TEXT NOT NULL,
          initiator_agent_id TEXT NOT NULL,
          responder_agent_id TEXT NOT NULL,
          status TEXT NOT NULL,
          payload JSONB NOT NULL,
          expires_at TIMESTAMPTZ NOT NULL,
          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
        )
      `;
      await this.sql`
        CREATE INDEX IF NOT EXISTS openclasp_federated_interactions_participants
        ON openclasp_federated_interactions(initiator_operator_id, responder_operator_id, updated_at DESC)
      `;
    })());
  }

  async upsert(
    operatorId: string,
    kind: HostedRecordKind,
    recordId: string,
    payload: unknown,
  ): Promise<void> {
    await this.ensureSchema();
    const encoded = JSON.stringify(payload);
    await this.sql`
      INSERT INTO openclasp_records(operator_id, kind, record_id, payload)
      VALUES (${operatorId}, ${kind}, ${recordId}, ${encoded}::jsonb)
      ON CONFLICT (operator_id, kind, record_id)
      DO UPDATE SET payload = EXCLUDED.payload, updated_at = NOW()
    `;
  }

  async list(
    operatorId: string,
  ): Promise<{ kind: HostedRecordKind; recordId: string; payload: any }[]> {
    await this.ensureSchema();
    const rows = await this.sql`
      SELECT kind, record_id, payload
      FROM openclasp_records
      WHERE operator_id = ${operatorId}
      ORDER BY created_at ASC
    `;
    return rows.map((row) => ({
      kind: row.kind as HostedRecordKind,
      recordId: String(row.record_id),
      payload: row.payload,
    }));
  }

  async dashboard(operatorId: string) {
    const rows = await this.list(operatorId);
    const federatedInteractions = await this.listFederatedInteractions(operatorId);
    const ofKind = (kind: HostedRecordKind) =>
      rows.filter((row) => row.kind === kind).map((row) => row.payload);
    return {
      agents: [...ofKind('agent_profile'), ...ofKind('agent')],
      projects: ofKind('project'),
      installations: ofKind('installation'),
      setupRequests: ofKind('setup_request'),
      publications: ofKind('publication'),
      interactions: ofKind('interaction'),
      events: ofKind('event'),
      conflicts: ofKind('conflict'),
      receipts: ofKind('receipt'),
      profiles: ofKind('profile'),
      federatedInteractions,
    };
  }

  async publishAgent(operatorId: string, card: PublicAgentCard): Promise<PublicAgentCard> {
    await this.ensureSchema();
    card = PublicAgentCardSchema.parse(card);
    const encoded = JSON.stringify(card);
    const rows = await this.sql`
      INSERT INTO openclasp_public_agents(agent_id, operator_id, card, published_at, updated_at)
      VALUES (${card.agentId}, ${operatorId}, ${encoded}::jsonb, NOW(), NOW())
      ON CONFLICT (agent_id) DO UPDATE SET
        card = EXCLUDED.card,
        updated_at = NOW()
      WHERE openclasp_public_agents.operator_id = ${operatorId}
      RETURNING card
    `;
    const published = rows[0]?.card as PublicAgentCard | undefined;
    if (!published) throw new Error('Agent ID is already owned by another operator');
    return published;
  }

  async unpublishAgent(operatorId: string, agentId: string): Promise<boolean> {
    await this.ensureSchema();
    const rows = await this.sql`
      DELETE FROM openclasp_public_agents
      WHERE agent_id = ${agentId} AND operator_id = ${operatorId}
      RETURNING agent_id
    `;
    return rows.length > 0;
  }

  async getPublishedAgent(agentId: string): Promise<PublicAgentCard | undefined> {
    await this.ensureSchema();
    const rows = await this.sql`
      SELECT card FROM openclasp_public_agents WHERE agent_id = ${agentId}
    `;
    return rows[0]?.card ? normalizePublicAgentCard(rows[0].card) : undefined;
  }

  async searchPublishedAgents(input: {
    query?: string | undefined;
    capability?: string | undefined;
    limit?: number | undefined;
  }): Promise<PublicAgentCard[]> {
    await this.ensureSchema();
    const rows = await this.sql`
      SELECT card FROM openclasp_public_agents ORDER BY updated_at DESC LIMIT 100
    `;
    const query = input.query?.trim().toLowerCase();
    const capability = input.capability?.trim().toLowerCase();
    return rows
      .map((row) => normalizePublicAgentCard(row.card))
      .filter(
        (card) =>
          (!query ||
            card.name.toLowerCase().includes(query) ||
            card.framework.toLowerCase().includes(query)) &&
          (!capability ||
            card.capabilities.some((value) => value.toLowerCase().includes(capability))),
      )
      .slice(0, Math.min(Math.max(input.limit ?? 20, 1), 50));
  }

  async createFederatedInteraction(
    operatorId: string,
    value: FederatedInteraction,
  ): Promise<FederatedInteraction> {
    await this.ensureSchema();
    const interaction = FederatedInteractionSchema.parse(value);
    if (interaction.status !== 'pending') throw new Error('New interactions must be pending');
    if (interaction.contract.interactionId !== interaction.interactionId)
      throw new Error('Contract interaction ID does not match');
    if (canonicalHash(interaction.contract) !== interaction.termsHash)
      throw new Error('Contract hash does not match the immutable terms');
    if (
      interaction.contract.parties.length !== 2 ||
      interaction.contract.parties[0] !== interaction.initiatorAgentId ||
      interaction.contract.parties[1] !== interaction.responderAgentId
    )
      throw new Error('Contract parties do not match the interaction participants');
    const acceptanceEntries = Object.entries(interaction.acceptances);
    if (
      acceptanceEntries.length !== 1 ||
      acceptanceEntries[0]?.[0] !== interaction.initiatorAgentId ||
      acceptanceEntries[0]?.[1].agentId !== interaction.initiatorAgentId ||
      acceptanceEntries[0]?.[1].termsHash !== interaction.termsHash ||
      !['oauth_installation', 'oauth_account'].includes(acceptanceEntries[0]?.[1].method ?? '')
    )
      throw new Error('A pending interaction requires only the initiator acceptance');
    if (Date.parse(interaction.expiresAt) <= Date.now())
      throw new Error('Interaction expiry must be in the future');
    const owners = await this.sql`
      SELECT agent_id, operator_id, card FROM openclasp_public_agents
      WHERE agent_id IN (${interaction.initiatorAgentId}, ${interaction.responderAgentId})
    `;
    const initiator = owners.find((row) => row.agent_id === interaction.initiatorAgentId);
    const responder = owners.find((row) => row.agent_id === interaction.responderAgentId);
    if (!initiator || initiator.operator_id !== operatorId)
      throw new Error('The initiating agent must be published and owned by this account');
    if (!responder) throw new Error('Responder is not a published OpenClasp agent');
    if (responder.operator_id === operatorId)
      throw new Error('Federated interactions require agents from different accounts');
    const responderCard = normalizePublicAgentCard(responder.card);
    if (
      !responderCard.transports.some(
        (transport) =>
          transport.endpoint === interaction.responderTransport.endpoint &&
          transport.protocolBinding === interaction.responderTransport.protocolBinding,
      )
    )
      throw new Error('Responder transport does not match its published Agent Card');
    const encoded = JSON.stringify(interaction);
    const rows = await this.sql`
      INSERT INTO openclasp_federated_interactions(
        interaction_id, initiator_operator_id, responder_operator_id,
        initiator_agent_id, responder_agent_id, status, payload, expires_at
      ) VALUES (
        ${interaction.interactionId}, ${operatorId}, ${responder.operator_id},
        ${interaction.initiatorAgentId}, ${interaction.responderAgentId},
        ${interaction.status}, ${encoded}::jsonb, ${interaction.expiresAt}
      )
      RETURNING payload
    `;
    return FederatedInteractionSchema.parse(rows[0]?.payload);
  }

  async listFederatedInteractions(operatorId: string): Promise<FederatedInteraction[]> {
    await this.ensureSchema();
    await this.sql`
      UPDATE openclasp_federated_interactions
      SET status = 'expired', payload = jsonb_set(payload, '{status}', '"expired"'::jsonb), updated_at = NOW()
      WHERE status = 'pending' AND expires_at <= NOW()
    `;
    const rows = await this.sql`
      SELECT payload FROM openclasp_federated_interactions
      WHERE initiator_operator_id = ${operatorId} OR responder_operator_id = ${operatorId}
      ORDER BY updated_at DESC
    `;
    return rows.map((row) => FederatedInteractionSchema.parse(row.payload));
  }

  async getFederatedInteraction(
    operatorId: string,
    interactionId: string,
  ): Promise<FederatedInteraction | undefined> {
    const values = await this.listFederatedInteractions(operatorId);
    return values.find((value) => value.interactionId === interactionId);
  }

  async respondToFederatedInteraction(
    operatorId: string,
    interactionId: string,
    agentId: string,
    decision: 'accept' | 'reject',
    method: 'oauth_installation' | 'oauth_account' = 'oauth_account',
  ): Promise<FederatedInteraction> {
    await this.ensureSchema();
    const rows = await this.sql`
      SELECT payload, responder_operator_id, responder_agent_id
      FROM openclasp_federated_interactions WHERE interaction_id = ${interactionId}
    `;
    const row = rows[0];
    if (!row) throw new Error('Interaction invitation not found');
    if (row.responder_operator_id !== operatorId || row.responder_agent_id !== agentId)
      throw new Error('Only the invited agent may respond');
    const current = FederatedInteractionSchema.parse(row.payload);
    if (current.status !== 'pending') throw new Error('Invitation is no longer pending');
    const now = new Date().toISOString();
    if (Date.parse(current.expiresAt) <= Date.now()) {
      const expired = { ...current, status: 'expired' as const, updatedAt: now };
      await this.updateFederatedInteraction(interactionId, current.status, expired);
      throw new Error('Invitation has expired');
    }
    const next: FederatedInteraction =
      decision === 'reject'
        ? { ...current, status: 'rejected', updatedAt: now }
        : {
            ...current,
            status: 'active',
            updatedAt: now,
            acceptances: {
              ...current.acceptances,
              [agentId]: {
                agentId,
                method,
                termsHash: current.termsHash,
                acceptedAt: now,
              },
            },
          };
    const updated = await this.updateFederatedInteraction(interactionId, current.status, next);
    if (!updated) throw new Error('Invitation was already handled');
    return next;
  }

  private async updateFederatedInteraction(
    interactionId: string,
    expectedStatus: string,
    value: FederatedInteraction,
  ): Promise<boolean> {
    const encoded = JSON.stringify(FederatedInteractionSchema.parse(value));
    const rows = await this.sql`
      UPDATE openclasp_federated_interactions
      SET status = ${value.status}, payload = ${encoded}::jsonb, updated_at = NOW()
      WHERE interaction_id = ${interactionId} AND status = ${expectedStatus}
      RETURNING interaction_id
    `;
    return rows.length > 0;
  }

  async getSettings(operatorId: string): Promise<AccountSettings> {
    await this.ensureSchema();
    const rows = await this.sql`
      SELECT display_name, contribution_enabled, retention_days, evidence_sharing
      FROM openclasp_account_settings
      WHERE operator_id = ${operatorId}
    `;
    const row = rows[0] as
      | {
          display_name: string;
          contribution_enabled: boolean;
          retention_days: number;
          evidence_sharing: AccountSettings['evidenceSharing'];
        }
      | undefined;
    return row
      ? {
          displayName: row.display_name,
          contributionEnabled: row.contribution_enabled,
          retentionDays: row.retention_days,
          evidenceSharing: row.evidence_sharing,
          rawConversationsStored: false,
        }
      : defaults;
  }

  async saveSettings(
    operatorId: string,
    settings: Omit<AccountSettings, 'rawConversationsStored'>,
  ): Promise<AccountSettings> {
    await this.ensureSchema();
    await this.sql`
      INSERT INTO openclasp_account_settings(
        operator_id, display_name, contribution_enabled, retention_days, evidence_sharing
      ) VALUES (
        ${operatorId}, ${settings.displayName}, ${settings.contributionEnabled},
        ${settings.retentionDays}, ${settings.evidenceSharing}
      )
      ON CONFLICT (operator_id) DO UPDATE SET
        display_name = EXCLUDED.display_name,
        contribution_enabled = EXCLUDED.contribution_enabled,
        retention_days = EXCLUDED.retention_days,
        evidence_sharing = EXCLUDED.evidence_sharing,
        updated_at = NOW()
    `;
    return { ...settings, rawConversationsStored: false };
  }
}

1	`import { neon, type NeonQueryFunction } from '@neondatabase/serverless';`
2	`import {`
3	`DEFAULT_EXTENSION_URI,`
4	`FederatedInteractionSchema,`
5	`PublicAgentCardSchema,`
6	`canonicalHash,`
7	`type FederatedInteraction,`
8	`type PublicAgentCard,`
9	`} from '../../protocol/src/index.js';`
10	`import type { AgentProfile } from './onboarding.js';`
11
12	`export type HostedRecordKind =`
13	`\| 'agent'`
14	`\| 'delegation'`
15	`\| 'contract'`
16	`\| 'interaction'`
17	`\| 'event'`
18	`\| 'receipt'`
19	`\| 'feedback'`
20	`\| 'conflict'`
21	`\| 'profile'`
22	`\| 'consent'`
23	`\| 'revocation'`
24	`\| 'project'`
25	`\| 'agent_profile'`
26	`\| 'installation'`
27	`\| 'setup_request'`
28	`\| 'publication';`
29
30	`export type { PublicAgentCard, FederatedInteraction } from '../../protocol/src/index.js';`
31
32	`function normalizePublicAgentCard(value: unknown): PublicAgentCard {`
33	`const current = PublicAgentCardSchema.safeParse(value);`
34	`if (current.success) return current.data;`
35	`const legacy = value as Record<string, unknown>;`
36	`const agentId = String(legacy.agentId ?? '');`
37	`const baseUrl = (process.env.OPENCLASP_PUBLIC_URL ?? 'https://openclasp.vercel.app').replace(`
38	`/\/$/,`
39	`'',`
40	`);`
41	`return PublicAgentCardSchema.parse({`
42	`protocolVersion: '0.1',`
43	`agentId,`
44	`name: legacy.name,`
45	`description: '',`
46	`framework: legacy.framework,`
47	`agentVersion: '1.0.0',`
48	`capabilities: legacy.capabilities,`
49	`limitations: legacy.limitations,`
50	`assurance: legacy.assurance,`
51	`transports: [],`
52	cardUrl: `${baseUrl}/agents/${encodeURIComponent(agentId)}/card.json`,
53	a2aAgentCardUrl: `${baseUrl}/agents/${encodeURIComponent(agentId)}/a2a-agent-card.json`,
54	`extensionUri: DEFAULT_EXTENSION_URI,`
55	`publishedAt: legacy.publishedAt,`
56	`updatedAt: legacy.updatedAt,`
57	`});`
58	`}`
59
60	`export function buildPublicAgentCard(`
61	`agent: AgentProfile,`
62	`baseUrl: string,`
63	`previous?: PublicAgentCard,`
64	`): PublicAgentCard {`
65	`const now = new Date().toISOString();`
66	`const root = baseUrl.replace(/\/$/, '');`
67	`return PublicAgentCardSchema.parse({`
68	`protocolVersion: '0.1',`
69	`agentId: agent.agentId,`
70	`name: agent.name,`
71	`description: agent.description ?? '',`
72	`framework: agent.framework,`
73	`agentVersion: agent.agentVersion ?? '1.0.0',`
74	`capabilities: agent.capabilities,`
75	`limitations: agent.limitations,`
76	`assurance: 'oauth_authenticated',`
77	`transports: agent.a2aEndpoint`
78	`? [{ protocol: 'A2A/1.0', protocolBinding: 'JSONRPC', endpoint: agent.a2aEndpoint }]`
79	`: [],`
80	cardUrl: `${root}/agents/${encodeURIComponent(agent.agentId)}/card.json`,
81	a2aAgentCardUrl: `${root}/agents/${encodeURIComponent(agent.agentId)}/a2a-agent-card.json`,
82	`extensionUri: DEFAULT_EXTENSION_URI,`
83	`publishedAt: previous?.publishedAt ?? now,`
84	`updatedAt: now,`
85	`});`
86	`}`
87
88	`export type AccountSettings = {`
89	`displayName: string;`
90	`contributionEnabled: boolean;`
91	`retentionDays: number;`
92	`evidenceSharing: 'never' \| 'ask' \| 'contract_only';`
93	`rawConversationsStored: false;`
94	`};`
95
96	`const defaults: AccountSettings = {`
97	`displayName: '',`
98	`contributionEnabled: false,`
99	`retentionDays: 30,`
100	`evidenceSharing: 'ask',`
101	`rawConversationsStored: false,`
102	`};`
103
104	`export class HostedRepository {`
105	`private readonly sql: NeonQueryFunction<false, false>;`
106	`private initialized?: Promise<void>;`
107
108	`constructor(databaseUrl: string) {`
109	`this.sql = neon(databaseUrl);`
110	`}`
111
112	`ensureSchema(): Promise<void> {`
113	`return (this.initialized ??= (async () => {`
114	await this.sql`
115	`CREATE TABLE IF NOT EXISTS openclasp_records (`
116	`operator_id TEXT NOT NULL,`
117	`kind TEXT NOT NULL,`
118	`record_id TEXT NOT NULL,`
119	`payload JSONB NOT NULL,`
120	`created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),`
121	`updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),`
122	`PRIMARY KEY (operator_id, kind, record_id)`
123	`)`
124	`;
125	await this.sql`
126	`CREATE INDEX IF NOT EXISTS openclasp_records_operator_created`
127	`ON openclasp_records(operator_id, created_at DESC)`
128	`;
129	await this.sql`
130	`CREATE TABLE IF NOT EXISTS openclasp_account_settings (`
131	`operator_id TEXT PRIMARY KEY,`
132	`display_name TEXT NOT NULL DEFAULT '',`
133	`contribution_enabled BOOLEAN NOT NULL DEFAULT FALSE,`
134	`retention_days INTEGER NOT NULL DEFAULT 30 CHECK (retention_days BETWEEN 0 AND 3650),`
135	`evidence_sharing TEXT NOT NULL DEFAULT 'ask'`
136	`CHECK (evidence_sharing IN ('never', 'ask', 'contract_only')),`
137	`updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
138	`)`
139	`;
140	await this.sql`
141	`CREATE TABLE IF NOT EXISTS openclasp_public_agents (`
142	`agent_id TEXT PRIMARY KEY,`
143	`operator_id TEXT NOT NULL,`
144	`card JSONB NOT NULL,`
145	`published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),`
146	`updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
147	`)`
148	`;
149	await this.sql`
150	`CREATE INDEX IF NOT EXISTS openclasp_public_agents_updated`
151	`ON openclasp_public_agents(updated_at DESC)`
152	`;
153	await this.sql`
154	`CREATE TABLE IF NOT EXISTS openclasp_federated_interactions (`
155	`interaction_id TEXT PRIMARY KEY,`
156	`initiator_operator_id TEXT NOT NULL,`
157	`responder_operator_id TEXT NOT NULL,`
158	`initiator_agent_id TEXT NOT NULL,`
159	`responder_agent_id TEXT NOT NULL,`
160	`status TEXT NOT NULL,`
161	`payload JSONB NOT NULL,`
162	`expires_at TIMESTAMPTZ NOT NULL,`
163	`created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),`
164	`updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
165	`)`
166	`;
167	await this.sql`
168	`CREATE INDEX IF NOT EXISTS openclasp_federated_interactions_participants`
169	`ON openclasp_federated_interactions(initiator_operator_id, responder_operator_id, updated_at DESC)`
170	`;
171	`})());`
172	`}`
173
174	`async upsert(`
175	`operatorId: string,`
176	`kind: HostedRecordKind,`
177	`recordId: string,`
178	`payload: unknown,`
179	`): Promise<void> {`
180	`await this.ensureSchema();`
181	`const encoded = JSON.stringify(payload);`
182	await this.sql`
183	`INSERT INTO openclasp_records(operator_id, kind, record_id, payload)`
184	`VALUES (${operatorId}, ${kind}, ${recordId}, ${encoded}::jsonb)`
185	`ON CONFLICT (operator_id, kind, record_id)`
186	`DO UPDATE SET payload = EXCLUDED.payload, updated_at = NOW()`
187	`;
188	`}`
189
190	`async list(`
191	`operatorId: string,`
192	`): Promise<{ kind: HostedRecordKind; recordId: string; payload: any }[]> {`
193	`await this.ensureSchema();`
194	const rows = await this.sql`
195	`SELECT kind, record_id, payload`
196	`FROM openclasp_records`
197	`WHERE operator_id = ${operatorId}`
198	`ORDER BY created_at ASC`
199	`;
200	`return rows.map((row) => ({`
201	`kind: row.kind as HostedRecordKind,`
202	`recordId: String(row.record_id),`
203	`payload: row.payload,`
204	`}));`
205	`}`
206
207	`async dashboard(operatorId: string) {`
208	`const rows = await this.list(operatorId);`
209	`const federatedInteractions = await this.listFederatedInteractions(operatorId);`
210	`const ofKind = (kind: HostedRecordKind) =>`
211	`rows.filter((row) => row.kind === kind).map((row) => row.payload);`
212	`return {`
213	`agents: [...ofKind('agent_profile'), ...ofKind('agent')],`
214	`projects: ofKind('project'),`
215	`installations: ofKind('installation'),`
216	`setupRequests: ofKind('setup_request'),`
217	`publications: ofKind('publication'),`
218	`interactions: ofKind('interaction'),`
219	`events: ofKind('event'),`
220	`conflicts: ofKind('conflict'),`
221	`receipts: ofKind('receipt'),`
222	`profiles: ofKind('profile'),`
223	`federatedInteractions,`
224	`};`
225	`}`
226
227	`async publishAgent(operatorId: string, card: PublicAgentCard): Promise<PublicAgentCard> {`
228	`await this.ensureSchema();`
229	`card = PublicAgentCardSchema.parse(card);`
230	`const encoded = JSON.stringify(card);`
231	const rows = await this.sql`
232	`INSERT INTO openclasp_public_agents(agent_id, operator_id, card, published_at, updated_at)`
233	`VALUES (${card.agentId}, ${operatorId}, ${encoded}::jsonb, NOW(), NOW())`
234	`ON CONFLICT (agent_id) DO UPDATE SET`
235	`card = EXCLUDED.card,`
236	`updated_at = NOW()`
237	`WHERE openclasp_public_agents.operator_id = ${operatorId}`
238	`RETURNING card`
239	`;
240	`const published = rows[0]?.card as PublicAgentCard \| undefined;`
241	`if (!published) throw new Error('Agent ID is already owned by another operator');`
242	`return published;`
243	`}`
244
245	`async unpublishAgent(operatorId: string, agentId: string): Promise<boolean> {`
246	`await this.ensureSchema();`
247	const rows = await this.sql`
248	`DELETE FROM openclasp_public_agents`
249	`WHERE agent_id = ${agentId} AND operator_id = ${operatorId}`
250	`RETURNING agent_id`
251	`;
252	`return rows.length > 0;`
253	`}`
254
255	`async getPublishedAgent(agentId: string): Promise<PublicAgentCard \| undefined> {`
256	`await this.ensureSchema();`
257	const rows = await this.sql`
258	`SELECT card FROM openclasp_public_agents WHERE agent_id = ${agentId}`
259	`;
260	`return rows[0]?.card ? normalizePublicAgentCard(rows[0].card) : undefined;`
261	`}`
262
263	`async searchPublishedAgents(input: {`
264	`query?: string \| undefined;`
265	`capability?: string \| undefined;`
266	`limit?: number \| undefined;`
267	`}): Promise<PublicAgentCard[]> {`
268	`await this.ensureSchema();`
269	const rows = await this.sql`
270	`SELECT card FROM openclasp_public_agents ORDER BY updated_at DESC LIMIT 100`
271	`;
272	`const query = input.query?.trim().toLowerCase();`
273	`const capability = input.capability?.trim().toLowerCase();`
274	`return rows`
275	`.map((row) => normalizePublicAgentCard(row.card))`
276	`.filter(`
277	`(card) =>`
278	`(!query \|\|`
279	`card.name.toLowerCase().includes(query) \|\|`
280	`card.framework.toLowerCase().includes(query)) &&`
281	`(!capability \|\|`
282	`card.capabilities.some((value) => value.toLowerCase().includes(capability))),`
283	`)`
284	`.slice(0, Math.min(Math.max(input.limit ?? 20, 1), 50));`
285	`}`
286
287	`async createFederatedInteraction(`
288	`operatorId: string,`
289	`value: FederatedInteraction,`
290	`): Promise<FederatedInteraction> {`
291	`await this.ensureSchema();`
292	`const interaction = FederatedInteractionSchema.parse(value);`
293	`if (interaction.status !== 'pending') throw new Error('New interactions must be pending');`
294	`if (interaction.contract.interactionId !== interaction.interactionId)`
295	`throw new Error('Contract interaction ID does not match');`
296	`if (canonicalHash(interaction.contract) !== interaction.termsHash)`
297	`throw new Error('Contract hash does not match the immutable terms');`
298	`if (`
299	`interaction.contract.parties.length !== 2 \|\|`
300	`interaction.contract.parties[0] !== interaction.initiatorAgentId \|\|`
301	`interaction.contract.parties[1] !== interaction.responderAgentId`
302	`)`
303	`throw new Error('Contract parties do not match the interaction participants');`
304	`const acceptanceEntries = Object.entries(interaction.acceptances);`
305	`if (`
306	`acceptanceEntries.length !== 1 \|\|`
307	`acceptanceEntries[0]?.[0] !== interaction.initiatorAgentId \|\|`
308	`acceptanceEntries[0]?.[1].agentId !== interaction.initiatorAgentId \|\|`
309	`acceptanceEntries[0]?.[1].termsHash !== interaction.termsHash \|\|`
310	`!['oauth_installation', 'oauth_account'].includes(acceptanceEntries[0]?.[1].method ?? '')`
311	`)`
312	`throw new Error('A pending interaction requires only the initiator acceptance');`
313	`if (Date.parse(interaction.expiresAt) <= Date.now())`
314	`throw new Error('Interaction expiry must be in the future');`
315	const owners = await this.sql`
316	`SELECT agent_id, operator_id, card FROM openclasp_public_agents`
317	`WHERE agent_id IN (${interaction.initiatorAgentId}, ${interaction.responderAgentId})`
318	`;
319	`const initiator = owners.find((row) => row.agent_id === interaction.initiatorAgentId);`
320	`const responder = owners.find((row) => row.agent_id === interaction.responderAgentId);`
321	`if (!initiator \|\| initiator.operator_id !== operatorId)`
322	`throw new Error('The initiating agent must be published and owned by this account');`
323	`if (!responder) throw new Error('Responder is not a published OpenClasp agent');`
324	`if (responder.operator_id === operatorId)`
325	`throw new Error('Federated interactions require agents from different accounts');`
326	`const responderCard = normalizePublicAgentCard(responder.card);`
327	`if (`
328	`!responderCard.transports.some(`
329	`(transport) =>`
330	`transport.endpoint === interaction.responderTransport.endpoint &&`
331	`transport.protocolBinding === interaction.responderTransport.protocolBinding,`
332	`)`
333	`)`
334	`throw new Error('Responder transport does not match its published Agent Card');`
335	`const encoded = JSON.stringify(interaction);`
336	const rows = await this.sql`
337	`INSERT INTO openclasp_federated_interactions(`
338	`interaction_id, initiator_operator_id, responder_operator_id,`
339	`initiator_agent_id, responder_agent_id, status, payload, expires_at`
340	`) VALUES (`
341	`${interaction.interactionId}, ${operatorId}, ${responder.operator_id},`
342	`${interaction.initiatorAgentId}, ${interaction.responderAgentId},`
343	`${interaction.status}, ${encoded}::jsonb, ${interaction.expiresAt}`
344	`)`
345	`RETURNING payload`
346	`;
347	`return FederatedInteractionSchema.parse(rows[0]?.payload);`
348	`}`
349
350	`async listFederatedInteractions(operatorId: string): Promise<FederatedInteraction[]> {`
351	`await this.ensureSchema();`
352	await this.sql`
353	`UPDATE openclasp_federated_interactions`
354	`SET status = 'expired', payload = jsonb_set(payload, '{status}', '"expired"'::jsonb), updated_at = NOW()`
355	`WHERE status = 'pending' AND expires_at <= NOW()`
356	`;
357	const rows = await this.sql`
358	`SELECT payload FROM openclasp_federated_interactions`
359	`WHERE initiator_operator_id = ${operatorId} OR responder_operator_id = ${operatorId}`
360	`ORDER BY updated_at DESC`
361	`;
362	`return rows.map((row) => FederatedInteractionSchema.parse(row.payload));`
363	`}`
364
365	`async getFederatedInteraction(`
366	`operatorId: string,`
367	`interactionId: string,`
368	`): Promise<FederatedInteraction \| undefined> {`
369	`const values = await this.listFederatedInteractions(operatorId);`
370	`return values.find((value) => value.interactionId === interactionId);`
371	`}`
372
373	`async respondToFederatedInteraction(`
374	`operatorId: string,`
375	`interactionId: string,`
376	`agentId: string,`
377	`decision: 'accept' \| 'reject',`
378	`method: 'oauth_installation' \| 'oauth_account' = 'oauth_account',`
379	`): Promise<FederatedInteraction> {`
380	`await this.ensureSchema();`
381	const rows = await this.sql`
382	`SELECT payload, responder_operator_id, responder_agent_id`
383	`FROM openclasp_federated_interactions WHERE interaction_id = ${interactionId}`
384	`;
385	`const row = rows[0];`
386	`if (!row) throw new Error('Interaction invitation not found');`
387	`if (row.responder_operator_id !== operatorId \|\| row.responder_agent_id !== agentId)`
388	`throw new Error('Only the invited agent may respond');`
389	`const current = FederatedInteractionSchema.parse(row.payload);`
390	`if (current.status !== 'pending') throw new Error('Invitation is no longer pending');`
391	`const now = new Date().toISOString();`
392	`if (Date.parse(current.expiresAt) <= Date.now()) {`
393	`const expired = { ...current, status: 'expired' as const, updatedAt: now };`
394	`await this.updateFederatedInteraction(interactionId, current.status, expired);`
395	`throw new Error('Invitation has expired');`
396	`}`
397	`const next: FederatedInteraction =`
398	`decision === 'reject'`
399	`? { ...current, status: 'rejected', updatedAt: now }`
400	`: {`
401	`...current,`
402	`status: 'active',`
403	`updatedAt: now,`
404	`acceptances: {`
405	`...current.acceptances,`
406	`[agentId]: {`
407	`agentId,`
408	`method,`
409	`termsHash: current.termsHash,`
410	`acceptedAt: now,`
411	`},`
412	`},`
413	`};`
414	`const updated = await this.updateFederatedInteraction(interactionId, current.status, next);`
415	`if (!updated) throw new Error('Invitation was already handled');`
416	`return next;`
417	`}`
418
419	`private async updateFederatedInteraction(`
420	`interactionId: string,`
421	`expectedStatus: string,`
422	`value: FederatedInteraction,`
423	`): Promise<boolean> {`
424	`const encoded = JSON.stringify(FederatedInteractionSchema.parse(value));`
425	const rows = await this.sql`
426	`UPDATE openclasp_federated_interactions`
427	`SET status = ${value.status}, payload = ${encoded}::jsonb, updated_at = NOW()`
428	`WHERE interaction_id = ${interactionId} AND status = ${expectedStatus}`
429	`RETURNING interaction_id`
430	`;
431	`return rows.length > 0;`
432	`}`
433
434	`async getSettings(operatorId: string): Promise<AccountSettings> {`
435	`await this.ensureSchema();`
436	const rows = await this.sql`
437	`SELECT display_name, contribution_enabled, retention_days, evidence_sharing`
438	`FROM openclasp_account_settings`
439	`WHERE operator_id = ${operatorId}`
440	`;
441	`const row = rows[0] as`
442	`\| {`
443	`display_name: string;`
444	`contribution_enabled: boolean;`
445	`retention_days: number;`
446	`evidence_sharing: AccountSettings['evidenceSharing'];`
447	`}`
448	`\| undefined;`
449	`return row`
450	`? {`
451	`displayName: row.display_name,`
452	`contributionEnabled: row.contribution_enabled,`
453	`retentionDays: row.retention_days,`
454	`evidenceSharing: row.evidence_sharing,`
455	`rawConversationsStored: false,`
456	`}`
457	`: defaults;`
458	`}`
459
460	`async saveSettings(`
461	`operatorId: string,`
462	`settings: Omit<AccountSettings, 'rawConversationsStored'>,`
463	`): Promise<AccountSettings> {`
464	`await this.ensureSchema();`
465	await this.sql`
466	`INSERT INTO openclasp_account_settings(`
467	`operator_id, display_name, contribution_enabled, retention_days, evidence_sharing`
468	`) VALUES (`
469	`${operatorId}, ${settings.displayName}, ${settings.contributionEnabled},`
470	`${settings.retentionDays}, ${settings.evidenceSharing}`
471	`)`
472	`ON CONFLICT (operator_id) DO UPDATE SET`
473	`display_name = EXCLUDED.display_name,`
474	`contribution_enabled = EXCLUDED.contribution_enabled,`
475	`retention_days = EXCLUDED.retention_days,`
476	`evidence_sharing = EXCLUDED.evidence_sharing,`
477	`updated_at = NOW()`
478	`;
479	`return { ...settings, rawConversationsStored: false };`
480	`}`
481	`}`