@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/seat/owner-card.ts

@@ -0,0 +1,388 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, relative, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { evaluateSeatReadiness, readSeatReadiness, type SeatReadinessStatus } from './readiness';
+
+export const AGENT_OWNER_CARD_SOURCE_SCHEMA = 'agent-owner-card-source.v0';
+export const AGENT_OWNER_CARD_SCHEMA = 'agent-owner-card.v0';
+export const AGENT_OWNER_CARD_PROJECTION_SCHEMA = 'agent-owner-card-projection.v0';
+
+type JsonRecord = Record<string, unknown>;
+
+export interface AgentOwnerFailureMode {
+  id: string;
+  description: string;
+  evidence_refs: string[];
+}
+
+export interface AgentOwnerCardSource {
+  schema: typeof AGENT_OWNER_CARD_SOURCE_SCHEMA;
+  seat_id: string;
+  job: string;
+  owner_principal: string;
+  maintainer: string;
+  diet_refs: string[];
+  authority_contract_ref: string;
+  allowed_work: string[];
+  forbidden_work: string[];
+  review: {
+    cadence: string;
+    last_reviewed_at: string;
+    stale_after: string;
+    event_triggers: string[];
+  };
+  failure_modes: AgentOwnerFailureMode[];
+}
+
+export interface AgentOwnerCard {
+  schema: typeof AGENT_OWNER_CARD_SCHEMA;
+  generated_at: string;
+  source_ref: string;
+  seat_id: string;
+  job: string;
+  accountability: {
+    owner_principal: string;
+    maintainer: string;
+    operator_principal_scope: 'per_run_receipts_only';
+    owner_is_not_operator: true;
+  };
+  diet_refs: string[];
+  current_occupant: null | {
+    source: 'seat-readiness.v0.1';
+    readiness_ref: string;
+    seat: string;
+    execution_surface: string;
+    model_tier: string;
+    effective_model_tier: string;
+    model_id: string | null;
+    operational_status: string;
+    capability_trusted: boolean;
+    is_stale: boolean;
+    last_heartbeat_at: string;
+    stale_after: string;
+  };
+  authority: {
+    source_ref: string;
+    allowed_work: string[];
+    forbidden_work: string[];
+    derived_from_contract: true;
+    card_may_edit_authority: false;
+  };
+  review: {
+    cadence: string;
+    last_reviewed_at: string;
+    stale_after: string;
+    is_stale: boolean;
+    event_driven_triggers: string[];
+  };
+  failure_modes: AgentOwnerFailureMode[];
+  warnings: string[];
+  authority_boundary: {
+    read_model_only: true;
+    can_authorize: false;
+    can_attach_grant: false;
+    can_change_owner: false;
+    can_edit_authority: false;
+    can_mutate_readiness: false;
+    can_merge: false;
+    can_close: false;
+  };
+}
+
+export interface AgentOwnerCardProjection {
+  schema: typeof AGENT_OWNER_CARD_PROJECTION_SCHEMA;
+  generated_at: string;
+  cards: AgentOwnerCard[];
+  validation_errors: Array<{ ref: string; reason: string }>;
+  authority_boundary: AgentOwnerCard['authority_boundary'];
+}
+
+const DEFAULT_EVENT_TRIGGERS = [
+  'model_switch',
+  'new_failure_mode',
+  'authority_change',
+  'seat_readiness_stale',
+] as const;
+
+function isoNow(at?: string): string {
+  const value = at ?? new Date().toISOString();
+  if (!Number.isFinite(Date.parse(value))) throw new Error('--at must be an ISO-8601 timestamp');
+  return new Date(value).toISOString();
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requireRecord(value: unknown, field: string): JsonRecord {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  return value;
+}
+
+function requireString(record: JsonRecord, key: string): string {
+  const value = record[key];
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${key} is required`);
+  }
+  assertSafeText(value, key);
+  return value.trim();
+}
+
+function optionalStringArray(record: JsonRecord, key: string): string[] {
+  const value = record[key];
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${key} must be a string array`);
+  return value.map((item, index) => {
+    if (typeof item !== 'string' || item.trim().length === 0) {
+      throw new Error(`${key}[${index}] must be a non-empty string`);
+    }
+    assertSafeText(item, `${key}[${index}]`);
+    return item.trim();
+  });
+}
+
+function requireStringArray(record: JsonRecord, key: string): string[] {
+  const values = optionalStringArray(record, key);
+  if (values.length === 0) throw new Error(`${key} must contain at least one item`);
+  return values;
+}
+
+function assertOpaqueId(value: string, field: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
+    throw new Error(`${field} must be an opaque id using letters, numbers, hyphen, or underscore`);
+  }
+}
+
+function assertSafeText(value: string, field: string): void {
+  if (value.length > 512) throw new Error(`${field} must be 512 characters or fewer`);
+  if (/[\u0000-\u001f]/.test(value)) throw new Error(`${field} must not contain control characters`);
+}
+
+function assertIso(value: string, field: string): void {
+  if (!Number.isFinite(Date.parse(value))) throw new Error(`${field} must be an ISO-8601 timestamp`);
+}
+
+function parseFailureModes(value: unknown): AgentOwnerFailureMode[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error('failure_modes must contain at least one item');
+  }
+  return value.map((item, index) => {
+    const record = requireRecord(item, `failure_modes[${index}]`);
+    const id = requireString(record, 'id');
+    assertOpaqueId(id, `failure_modes[${index}].id`);
+    const description = requireString(record, 'description');
+    const evidenceRefs = requireStringArray(record, 'evidence_refs');
+    return { id, description, evidence_refs: evidenceRefs };
+  });
+}
+
+function parseSource(raw: unknown): AgentOwnerCardSource {
+  const record = requireRecord(raw, 'agent owner card source');
+  if (record.schema !== AGENT_OWNER_CARD_SOURCE_SCHEMA) {
+    throw new Error(`schema must be ${AGENT_OWNER_CARD_SOURCE_SCHEMA}`);
+  }
+  if ('current_occupant' in record || 'occupant' in record || 'model_id' in record || 'model_tier' in record) {
+    throw new Error('current occupant and model posture are derived from seat-readiness, not authored on the owner card source');
+  }
+  const seatId = requireString(record, 'seat_id');
+  assertOpaqueId(seatId, 'seat_id');
+  const ownerPrincipal = requireString(record, 'owner_principal');
+  assertOpaqueId(ownerPrincipal, 'owner_principal');
+  const maintainer = requireString(record, 'maintainer');
+  assertOpaqueId(maintainer, 'maintainer');
+  const review = requireRecord(record.review, 'review');
+  const lastReviewedAt = requireString(review, 'last_reviewed_at');
+  const staleAfter = requireString(review, 'stale_after');
+  assertIso(lastReviewedAt, 'review.last_reviewed_at');
+  assertIso(staleAfter, 'review.stale_after');
+  return {
+    schema: AGENT_OWNER_CARD_SOURCE_SCHEMA,
+    seat_id: seatId,
+    job: requireString(record, 'job'),
+    owner_principal: ownerPrincipal,
+    maintainer,
+    diet_refs: requireStringArray(record, 'diet_refs'),
+    authority_contract_ref: requireString(record, 'authority_contract_ref'),
+    allowed_work: requireStringArray(record, 'allowed_work'),
+    forbidden_work: requireStringArray(record, 'forbidden_work'),
+    review: {
+      cadence: requireString(review, 'cadence'),
+      last_reviewed_at: new Date(lastReviewedAt).toISOString(),
+      stale_after: new Date(staleAfter).toISOString(),
+      event_triggers: optionalStringArray(review, 'event_triggers'),
+    },
+    failure_modes: parseFailureModes(record.failure_modes),
+  };
+}
+
+async function readStructured(path: string): Promise<unknown> {
+  const raw = await readFile(path, 'utf-8');
+  if (extname(path).toLowerCase() === '.json') return JSON.parse(raw) as unknown;
+  return parseYaml(raw) as unknown;
+}
+
+function projectRelative(projectRoot: string, path: string): string {
+  const rel = relative(resolve(projectRoot), resolve(path));
+  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
+    throw new Error(`path must stay inside project root: ${path}`);
+  }
+  return rel;
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function currentOccupant(
+  status: SeatReadinessStatus | null,
+  readinessRef: string,
+): AgentOwnerCard['current_occupant'] {
+  if (!status) return null;
+  return {
+    source: 'seat-readiness.v0.1',
+    readiness_ref: readinessRef,
+    seat: status.seat,
+    execution_surface: status.execution_surface,
+    model_tier: status.model_tier,
+    effective_model_tier: status.effective_model_tier,
+    model_id: status.model_id ?? null,
+    operational_status: status.operational_status,
+    capability_trusted: status.capability_trusted,
+    is_stale: status.is_stale,
+    last_heartbeat_at: status.last_heartbeat_at,
+    stale_after: status.stale_after,
+  };
+}
+
+function boundary(): AgentOwnerCard['authority_boundary'] {
+  return {
+    read_model_only: true,
+    can_authorize: false,
+    can_attach_grant: false,
+    can_change_owner: false,
+    can_edit_authority: false,
+    can_mutate_readiness: false,
+    can_merge: false,
+    can_close: false,
+  };
+}
+
+export async function buildAgentOwnerCard(options: {
+  projectRoot: string;
+  manifestPath: string;
+  statePath?: string;
+  at?: string;
+}): Promise<AgentOwnerCard> {
+  const root = resolve(options.projectRoot);
+  const generatedAt = isoNow(options.at);
+  const manifestPath = resolve(options.manifestPath);
+  const source = parseSource(await readStructured(manifestPath));
+  const sourceRef = projectRelative(root, manifestPath);
+  const readinessRef = options.statePath
+    ? projectRelative(root, resolve(options.statePath))
+    : '.etiquette/state/seat-readiness.json';
+
+  let readiness: SeatReadinessStatus | null = null;
+  const warnings: string[] = [];
+  try {
+    const record = await readSeatReadiness(root, options.statePath);
+    readiness = evaluateSeatReadiness(record, generatedAt);
+    if (readiness.seat !== source.seat_id) warnings.push('seat_readiness_mismatch');
+    if (readiness.is_stale) warnings.push('seat_readiness_stale');
+  } catch (err) {
+    warnings.push(`seat_readiness_unavailable:${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const reviewIsStale = Date.parse(generatedAt) > Date.parse(source.review.stale_after);
+  if (reviewIsStale) warnings.push('owner_card_review_stale');
+
+  return {
+    schema: AGENT_OWNER_CARD_SCHEMA,
+    generated_at: generatedAt,
+    source_ref: sourceRef,
+    seat_id: source.seat_id,
+    job: source.job,
+    accountability: {
+      owner_principal: source.owner_principal,
+      maintainer: source.maintainer,
+      operator_principal_scope: 'per_run_receipts_only',
+      owner_is_not_operator: true,
+    },
+    diet_refs: source.diet_refs,
+    current_occupant: currentOccupant(readiness, readinessRef),
+    authority: {
+      source_ref: source.authority_contract_ref,
+      allowed_work: source.allowed_work,
+      forbidden_work: source.forbidden_work,
+      derived_from_contract: true,
+      card_may_edit_authority: false,
+    },
+    review: {
+      cadence: source.review.cadence,
+      last_reviewed_at: source.review.last_reviewed_at,
+      stale_after: source.review.stale_after,
+      is_stale: reviewIsStale,
+      event_driven_triggers: unique([...DEFAULT_EVENT_TRIGGERS, ...source.review.event_triggers]),
+    },
+    failure_modes: source.failure_modes,
+    warnings,
+    authority_boundary: boundary(),
+  };
+}
+
+async function collectFiles(dir: string): Promise<string[]> {
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return collectFiles(path);
+    return entry.isFile() ? [path] : [];
+  }));
+  return nested.flat().sort();
+}
+
+export async function buildAgentOwnerCardProjection(options: {
+  projectRoot: string;
+  statePath?: string;
+  at?: string;
+}): Promise<AgentOwnerCardProjection> {
+  const root = resolve(options.projectRoot);
+  const generatedAt = isoNow(options.at);
+  const candidates = [
+    join(root, '.etiquette', 'seats', 'owner-card.yaml'),
+    join(root, '.etiquette', 'seats', 'owner-card.yml'),
+    join(root, '.etiquette', 'seats', 'owner-card.json'),
+    ...(await collectFiles(join(root, '.etiquette', 'seats', 'owner-cards'))),
+    ...(await collectFiles(join(root, 'docs', 'work', 'seats', 'owner-cards'))),
+  ].filter((path, index, all) => {
+    const ext = extname(path).toLowerCase();
+    return existsSync(path) && ['.yaml', '.yml', '.json'].includes(ext) && all.indexOf(path) === index;
+  });
+
+  const cards: AgentOwnerCard[] = [];
+  const validationErrors: AgentOwnerCardProjection['validation_errors'] = [];
+  for (const manifestPath of candidates) {
+    try {
+      cards.push(await buildAgentOwnerCard({
+        projectRoot: root,
+        manifestPath,
+        statePath: options.statePath,
+        at: generatedAt,
+      }));
+    } catch (err) {
+      validationErrors.push({
+        ref: projectRelative(root, manifestPath),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return {
+    schema: AGENT_OWNER_CARD_PROJECTION_SCHEMA,
+    generated_at: generatedAt,
+    cards,
+    validation_errors: validationErrors,
+    authority_boundary: boundary(),
+  };
+}