@agent-native/core 0.90.2 → 0.90.3

package/corpus/core/src/history/actions/restore-resource-version.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import {
+  assertVersionedResourceAccess,
+  getVersionedResource,
+} from "../registry.js";
+import {
+  getResourceVersionById,
+  getResourceVersionByNumber,
+} from "../store.js";
+import type { VersionedResourceContext } from "../types.js";
+
+const schema = z
+  .object({
+    id: z.string().optional(),
+    resourceType: z.string().min(1).optional(),
+    resourceId: z.string().min(1).optional(),
+    versionNumber: z.number().int().positive().optional(),
+  })
+  .refine(
+    (value) =>
+      value.id ||
+      (value.resourceType && value.resourceId && value.versionNumber),
+    {
+      message:
+        "Provide either id or resourceType, resourceId, and versionNumber",
+    },
+  );
+
+export default defineAction({
+  description: "Restore a resource from a reusable version-history snapshot.",
+  schema,
+  run: async (args, ctx) => {
+    const actionCtx = ctx as VersionedResourceContext | undefined;
+    const scope = {
+      userEmail: actionCtx?.userEmail ?? null,
+      orgId: actionCtx?.orgId ?? null,
+    };
+    const version = args.id
+      ? await getResourceVersionById(args.id, scope, { bypassScope: true })
+      : await getResourceVersionByNumber(
+          args.resourceType!,
+          args.resourceId!,
+          args.versionNumber!,
+          scope,
+          { bypassScope: true },
+        );
+    if (!version) {
+      throw new Error("Resource version not found");
+    }
+
+    const access = await assertVersionedResourceAccess(
+      version.resourceType,
+      version.resourceId,
+      actionCtx,
+      "editor",
+    );
+    const registration = getVersionedResource(version.resourceType);
+    if (!registration?.restoreSnapshot) {
+      throw new Error(
+        `${version.resourceType} has no restoreSnapshot history handler registered`,
+      );
+    }
+
+    const result = await registration.restoreSnapshot({
+      resourceType: version.resourceType,
+      resourceId: version.resourceId,
+      ctx: actionCtx,
+      access,
+      version,
+      snapshot: version.snapshot,
+    });
+    return { version, result };
+  },
+  audit: {
+    target: (_args, result) => {
+      const restored = result as {
+        version: {
+          resourceType: string;
+          resourceId: string;
+          ownerEmail?: string | null;
+          orgId?: string | null;
+          visibility?: "private" | "org" | "public";
+        };
+      };
+      return {
+        type: restored.version.resourceType,
+        id: restored.version.resourceId,
+        ownerEmail: restored.version.ownerEmail,
+        orgId: restored.version.orgId,
+        visibility: restored.version.visibility,
+      };
+    },
+  },
+});

package/corpus/core/src/history/index.ts

@@ -0,0 +1,27 @@
+export type {
+  HistoryActorKind,
+  HistoryResourceRole,
+  ResourceHistoryScope,
+  ResourceVersion,
+  VersionedResourceAccess,
+  VersionedResourceContext,
+  VersionedResourceRegistration,
+  VersionedResourceRestoreContext,
+  VersionedResourceSnapshotContext,
+} from "./types.js";
+export {
+  __resetVersionedResourcesForTests,
+  assertVersionedResourceAccess,
+  getVersionedResource,
+  listVersionedResources,
+  registerVersionedResource,
+  resolveVersionedResourceAccess,
+} from "./registry.js";
+export {
+  __resetHistoryInitForTests,
+  ensureResourceVersionsTable,
+  getResourceVersionById,
+  getResourceVersionByNumber,
+  insertResourceVersion,
+  queryResourceVersions,
+} from "./store.js";

package/corpus/core/src/history/registry.ts

@@ -0,0 +1,99 @@
+import { ForbiddenError, resolveAccess } from "../sharing/access.js";
+import { getShareableResource } from "../sharing/registry.js";
+import { roleSatisfies, type Visibility } from "../sharing/schema.js";
+import type {
+  HistoryResourceRole,
+  VersionedResourceAccess,
+  VersionedResourceContext,
+  VersionedResourceRegistration,
+} from "./types.js";
+
+const registrations = new Map<string, VersionedResourceRegistration>();
+
+export function registerVersionedResource(
+  registration: VersionedResourceRegistration,
+): void {
+  if (!registration.type.trim()) {
+    throw new Error(
+      "registerVersionedResource requires a non-empty resource type",
+    );
+  }
+  registrations.set(registration.type, registration);
+}
+
+export function getVersionedResource(
+  type: string,
+): VersionedResourceRegistration | undefined {
+  return registrations.get(type);
+}
+
+export function listVersionedResources(): VersionedResourceRegistration[] {
+  return Array.from(registrations.values());
+}
+
+export async function resolveVersionedResourceAccess(
+  resourceType: string,
+  resourceId: string,
+  ctx?: VersionedResourceContext,
+): Promise<VersionedResourceAccess | null> {
+  const registration = getVersionedResource(resourceType);
+  if (registration?.resolveAccess) {
+    return registration.resolveAccess(resourceId, ctx);
+  }
+
+  if (getShareableResource(resourceType)) {
+    const access = await resolveAccess(resourceType, resourceId);
+    if (!access) {
+      return null;
+    }
+    return {
+      role: access.role as HistoryResourceRole,
+      ownerEmail: access.resource.ownerEmail ?? null,
+      orgId: access.resource.orgId ?? null,
+      visibility: access.resource.visibility,
+      resource: access.resource,
+    };
+  }
+
+  const userEmail = ctx?.userEmail ?? null;
+  if (!userEmail) {
+    return null;
+  }
+  return {
+    role: "owner",
+    ownerEmail: userEmail,
+    orgId: ctx?.orgId ?? null,
+    visibility: "private",
+  };
+}
+
+export async function assertVersionedResourceAccess(
+  resourceType: string,
+  resourceId: string,
+  ctx: VersionedResourceContext | undefined,
+  minimumRole: HistoryResourceRole,
+): Promise<VersionedResourceAccess> {
+  const access = await resolveVersionedResourceAccess(
+    resourceType,
+    resourceId,
+    ctx,
+  );
+  if (!access || !roleSatisfies(access.role, minimumRole)) {
+    throw new ForbiddenError(
+      `Not allowed to access ${resourceType}:${resourceId}`,
+    );
+  }
+  return access;
+}
+
+export function normalizeHistoryVisibility(
+  visibility: Visibility | null | undefined,
+): Visibility {
+  return visibility === "org" || visibility === "public"
+    ? visibility
+    : "private";
+}
+
+export function __resetVersionedResourcesForTests(): void {
+  registrations.clear();
+}

package/corpus/core/src/history/store.ts

@@ -0,0 +1,348 @@
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+import type { Visibility } from "../sharing/schema.js";
+import type {
+  HistoryActorKind,
+  ResourceHistoryScope,
+  ResourceVersion,
+} from "./types.js";
+
+let historyTableInitPromise: Promise<void> | undefined;
+
+export interface InsertResourceVersionInput {
+  resourceType: string;
+  resourceId: string;
+  createdBy?: string | null;
+  actorKind?: HistoryActorKind;
+  ownerEmail?: string | null;
+  orgId?: string | null;
+  visibility?: Visibility | null;
+  title?: string | null;
+  summary?: string | null;
+  snapshot: unknown;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface QueryResourceVersionsInput {
+  resourceType: string;
+  resourceId: string;
+  scope: ResourceHistoryScope;
+  bypassScope?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+export async function ensureResourceVersionsTable(): Promise<void> {
+  if (!historyTableInitPromise) {
+    historyTableInitPromise = (async () => {
+      const client = getDbExec();
+      const createSql = `CREATE TABLE IF NOT EXISTS agent_resource_versions (
+      id TEXT PRIMARY KEY,
+      resource_type TEXT NOT NULL,
+      resource_id TEXT NOT NULL,
+      version_number ${intType()} NOT NULL,
+      created_at TEXT NOT NULL,
+      created_by TEXT,
+      actor_kind TEXT NOT NULL DEFAULT 'human',
+      owner_email TEXT,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      title TEXT,
+      summary TEXT,
+      snapshot_json TEXT NOT NULL,
+      metadata_json TEXT
+    )`;
+      const indexes = [
+        `CREATE INDEX IF NOT EXISTS idx_agent_resource_versions_resource
+           ON agent_resource_versions (resource_type, resource_id, version_number)`,
+        `CREATE INDEX IF NOT EXISTS idx_agent_resource_versions_owner
+           ON agent_resource_versions (owner_email, created_at)`,
+        `CREATE INDEX IF NOT EXISTS idx_agent_resource_versions_org
+           ON agent_resource_versions (org_id, created_at)`,
+      ];
+
+      if (isPostgres()) {
+        await ensureTableExists("agent_resource_versions", createSql);
+        await ensureIndexExists(
+          "idx_agent_resource_versions_resource",
+          indexes[0],
+        );
+        await ensureIndexExists(
+          "idx_agent_resource_versions_owner",
+          indexes[1],
+        );
+        await ensureIndexExists("idx_agent_resource_versions_org", indexes[2]);
+      } else {
+        await client.execute(createSql);
+        for (const indexSql of indexes) {
+          await client.execute(indexSql);
+        }
+      }
+    })();
+  }
+
+  await historyTableInitPromise;
+}
+
+export async function insertResourceVersion(
+  input: InsertResourceVersionInput,
+): Promise<ResourceVersion> {
+  await ensureResourceVersionsTable();
+  const client = getDbExec();
+  const maxRows = await client.execute({
+    sql: `SELECT MAX(version_number) as max_version
+       FROM agent_resource_versions
+      WHERE resource_type = ? AND resource_id = ?`,
+    args: [input.resourceType, input.resourceId],
+  });
+  const versionNumber =
+    Number(
+      (maxRows.rows?.[0] as Record<string, unknown> | undefined)?.max_version ??
+        0,
+    ) + 1;
+  const id = createVersionId();
+  const createdAt = new Date().toISOString();
+  const version: ResourceVersion = {
+    id,
+    resourceType: input.resourceType,
+    resourceId: input.resourceId,
+    versionNumber,
+    createdAt,
+    createdBy: input.createdBy ?? null,
+    actorKind: input.actorKind ?? "human",
+    ownerEmail: input.ownerEmail ?? input.createdBy ?? null,
+    orgId: input.orgId ?? null,
+    visibility:
+      input.visibility === "org" || input.visibility === "public"
+        ? input.visibility
+        : "private",
+    title: input.title ?? null,
+    summary: input.summary ?? null,
+    snapshot: input.snapshot,
+    metadata: input.metadata ?? null,
+  };
+
+  await client.execute({
+    sql: `INSERT INTO agent_resource_versions (
+      id,
+      resource_type,
+      resource_id,
+      version_number,
+      created_at,
+      created_by,
+      actor_kind,
+      owner_email,
+      org_id,
+      visibility,
+      title,
+      summary,
+      snapshot_json,
+      metadata_json
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      version.id,
+      version.resourceType,
+      version.resourceId,
+      version.versionNumber,
+      version.createdAt,
+      version.createdBy,
+      version.actorKind,
+      version.ownerEmail,
+      version.orgId,
+      version.visibility,
+      version.title,
+      version.summary,
+      JSON.stringify(version.snapshot),
+      stringifyOptionalJson(version.metadata),
+    ],
+  });
+
+  return version;
+}
+
+export async function queryResourceVersions(
+  input: QueryResourceVersionsInput,
+): Promise<ResourceVersion[]> {
+  await ensureResourceVersionsTable();
+  const client = getDbExec();
+  const { clause, params } = input.bypassScope
+    ? { clause: "1 = 1", params: [] as unknown[] }
+    : scopedResourceClause(input.scope);
+  const limit = clampLimit(input.limit);
+  const offset = Math.max(0, Math.floor(input.offset ?? 0));
+  const result = await client.execute({
+    sql: `SELECT ${listColumns()}
+       FROM agent_resource_versions
+      WHERE resource_type = ? AND resource_id = ? AND ${clause}
+      ORDER BY version_number DESC
+      LIMIT ? OFFSET ?`,
+    args: [input.resourceType, input.resourceId, ...params, limit, offset],
+  });
+  return (result.rows ?? []).map((row) => mapVersionRow(row, false));
+}
+
+export async function getResourceVersionById(
+  id: string,
+  scope: ResourceHistoryScope,
+  options: { bypassScope?: boolean } = {},
+): Promise<ResourceVersion | null> {
+  await ensureResourceVersionsTable();
+  const client = getDbExec();
+  const { clause, params } = options.bypassScope
+    ? { clause: "1 = 1", params: [] as unknown[] }
+    : scopedResourceClause(scope);
+  const result = await client.execute({
+    sql: `SELECT ${allColumns()}
+       FROM agent_resource_versions
+      WHERE id = ? AND ${clause}
+      LIMIT 1`,
+    args: [id, ...params],
+  });
+  const row = result.rows?.[0];
+  return row ? mapVersionRow(row, true) : null;
+}
+
+export async function getResourceVersionByNumber(
+  resourceType: string,
+  resourceId: string,
+  versionNumber: number,
+  scope: ResourceHistoryScope,
+  options: { bypassScope?: boolean } = {},
+): Promise<ResourceVersion | null> {
+  await ensureResourceVersionsTable();
+  const client = getDbExec();
+  const { clause, params } = options.bypassScope
+    ? { clause: "1 = 1", params: [] as unknown[] }
+    : scopedResourceClause(scope);
+  const result = await client.execute({
+    sql: `SELECT ${allColumns()}
+       FROM agent_resource_versions
+      WHERE resource_type = ?
+        AND resource_id = ?
+        AND version_number = ?
+        AND ${clause}
+      LIMIT 1`,
+    args: [resourceType, resourceId, versionNumber, ...params],
+  });
+  const row = result.rows?.[0];
+  return row ? mapVersionRow(row, true) : null;
+}
+
+export function __resetHistoryInitForTests(): void {
+  historyTableInitPromise = undefined;
+}
+
+function listColumns(): string {
+  return [
+    "id",
+    "resource_type",
+    "resource_id",
+    "version_number",
+    "created_at",
+    "created_by",
+    "actor_kind",
+    "owner_email",
+    "org_id",
+    "visibility",
+    "title",
+    "summary",
+    "metadata_json",
+  ].join(", ");
+}
+
+function allColumns(): string {
+  return `${listColumns()}, snapshot_json`;
+}
+
+function scopedResourceClause(scope: ResourceHistoryScope): {
+  clause: string;
+  params: unknown[];
+} {
+  const parts: string[] = [];
+  const params: unknown[] = [];
+
+  if (scope.userEmail) {
+    parts.push("owner_email = ?");
+    params.push(scope.userEmail);
+  }
+  if (scope.orgId) {
+    parts.push("(visibility = 'org' AND org_id = ?)");
+    params.push(scope.orgId);
+  }
+  parts.push("visibility = 'public'");
+
+  if (parts.length === 0) {
+    return { clause: "visibility = 'public'", params: [] };
+  }
+
+  return { clause: `(${parts.join(" OR ")})`, params };
+}
+
+function mapVersionRow(
+  row: Record<string, unknown>,
+  includeSnapshot: boolean,
+): ResourceVersion {
+  const version: ResourceVersion = {
+    id: String(row.id),
+    resourceType: String(row.resource_type),
+    resourceId: String(row.resource_id),
+    versionNumber: Number(row.version_number),
+    createdAt: String(row.created_at),
+    createdBy: nullableString(row.created_by),
+    actorKind: normalizeActorKind(row.actor_kind),
+    ownerEmail: nullableString(row.owner_email),
+    orgId: nullableString(row.org_id),
+    visibility: normalizeVisibility(row.visibility),
+    title: nullableString(row.title),
+    summary: nullableString(row.summary),
+    metadata: parseOptionalJson(row.metadata_json),
+  };
+  if (includeSnapshot) {
+    version.snapshot = parseRequiredJson(row.snapshot_json);
+  }
+  return version;
+}
+
+function createVersionId(): string {
+  return `ver_${globalThis.crypto.randomUUID()}`;
+}
+
+function clampLimit(value: number | undefined): number {
+  if (!Number.isFinite(value)) {
+    return 50;
+  }
+  return Math.min(200, Math.max(1, Math.floor(value ?? 50)));
+}
+
+function nullableString(value: unknown): string | null {
+  return value === null || value === undefined ? null : String(value);
+}
+
+function normalizeVisibility(value: unknown): Visibility {
+  return value === "org" || value === "public" ? value : "private";
+}
+
+function normalizeActorKind(value: unknown): HistoryActorKind {
+  return value === "agent" || value === "system" ? value : "human";
+}
+
+function stringifyOptionalJson(value: unknown): string | null {
+  return value === null || value === undefined ? null : JSON.stringify(value);
+}
+
+function parseOptionalJson(value: unknown): Record<string, unknown> | null {
+  if (value === null || value === undefined || value === "") {
+    return null;
+  }
+  const parsed = parseRequiredJson(value);
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : null;
+}
+
+function parseRequiredJson(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return JSON.parse(value);
+}

package/corpus/core/src/history/types.ts

@@ -0,0 +1,69 @@
+import type { Visibility } from "../sharing/schema.js";
+
+export type HistoryActorKind = "human" | "agent" | "system";
+export type HistoryResourceRole = "viewer" | "editor" | "admin" | "owner";
+
+export interface VersionedResourceAccess {
+  role: HistoryResourceRole;
+  ownerEmail?: string | null;
+  orgId?: string | null;
+  visibility?: Visibility | null;
+  resource?: unknown;
+}
+
+export interface VersionedResourceContext {
+  userEmail?: string | null;
+  orgId?: string | null;
+  caller?: string | null;
+  request?: unknown;
+  [key: string]: unknown;
+}
+
+export interface VersionedResourceSnapshotContext {
+  resourceType: string;
+  resourceId: string;
+  ctx?: VersionedResourceContext;
+  access?: VersionedResourceAccess;
+}
+
+export interface VersionedResourceRestoreContext extends VersionedResourceSnapshotContext {
+  version: ResourceVersion;
+  snapshot: unknown;
+}
+
+export interface VersionedResourceRegistration {
+  type: string;
+  displayName?: string;
+  resolveAccess?: (
+    resourceId: string,
+    ctx?: VersionedResourceContext,
+  ) => Promise<VersionedResourceAccess | null> | VersionedResourceAccess | null;
+  getSnapshot?: (
+    context: VersionedResourceSnapshotContext,
+  ) => Promise<unknown> | unknown;
+  restoreSnapshot?: (
+    context: VersionedResourceRestoreContext,
+  ) => Promise<unknown> | unknown;
+}
+
+export interface ResourceVersion {
+  id: string;
+  resourceType: string;
+  resourceId: string;
+  versionNumber: number;
+  createdAt: string;
+  createdBy: string | null;
+  actorKind: HistoryActorKind;
+  ownerEmail: string | null;
+  orgId: string | null;
+  visibility: Visibility;
+  title: string | null;
+  summary: string | null;
+  snapshot?: unknown;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface ResourceHistoryScope {
+  userEmail?: string | null;
+  orgId?: string | null;
+}

package/corpus/core/src/index.ts

@@ -336,3 +336,13 @@ export {
   type SecretValidator,
   type SecretRef,
 } from "./secrets/index.js";
+
+export * from "./history/index.js";
+export * from "./review/index.js";
+export * from "./org-team/index.js";
+export * from "./navigation/index.js";
+export * from "./command-navigation/index.js";
+export {
+  registerWorkspaceConnectionOnboardingStep,
+  type RegisterWorkspaceConnectionOnboardingStepOptions,
+} from "./setup-connections/index.js";