@stage-labs/metro 0.1.0-beta.277 → 0.1.0-beta.278

package/dist/automation.js

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { findBun, runtimeDir } from './runtime.js';
+const TASK_HELP = `metro task: queue work for the existing Agent SDK conversation
+
+  metro task submit <routine> <prompt-file> [--slot <UTC ISO timestamp>] [--dry-run]
+                  queue a local prompt file (regular UTF-8 file, at most 64 KiB);
+                  default slot is the current UTC hour; use --slot for other cadences;
+                  accepted means saved, not executed; duplicates show their current state;
+                  --dry-run writes nothing
+  metro task status [routine]
+                  read safe local metadata, including the token needed to finish;
+                  never print prompts
+  metro task finish <uuid> <token> completed|blocked
+                  save a receipt pending runner verification, not mark work complete
+
+  These commands never start a session, install a runtime or connect to the daemon.
+  Local task authorization is not fresh owner approval for external actions.
+`;
+function taskRuntime() {
+    let dir;
+    try {
+        dir = runtimeDir();
+    }
+    catch {
+        throw new Error('metro task needs the shipped runtime; reinstall @stage-labs/metro@beta');
+    }
+    const entry = join(dir, 'sdk-runner', 'src', 'automation-cli.ts');
+    if (!existsSync(entry))
+        throw new Error('metro task is missing its shipped entry; reinstall @stage-labs/metro@beta');
+    try {
+        return { bun: findBun(), entry };
+    }
+    catch {
+        throw new Error('metro task needs Bun on PATH; it never installs Bun or the runner');
+    }
+}
+export async function automationCommand(args) {
+    if (args.length === 0 || (args.length === 1 && ['help', '--help', '-h'].includes(args[0] ?? ''))) {
+        process.stderr.write(TASK_HELP);
+        return args.length === 0 ? 1 : 0;
+    }
+    const { bun, entry } = taskRuntime();
+    return new Promise((resolve) => {
+        const child = spawn(bun, ['--no-install', entry, ...args], {
+            stdio: ['ignore', 'inherit', 'inherit'],
+            env: { ...process.env, BUN_RUNTIME_TRANSPILER_CACHE_PATH: '0' },
+        });
+        child.once('error', () => {
+            process.stderr.write('metro task: unable to run the shipped task command\n');
+            resolve(1);
+        });
+        child.once('exit', (code) => { resolve(code ?? 1); });
+    });
+}

package/dist/cli.js

@@ -3,6 +3,7 @@ import { whoisAuthorized } from './api.js';
 import { stopAll } from './control.js';
 import { tailEvents } from './tail.js';
 import { agentSession } from './agent.js';
+import { automationCommand } from './automation.js';
 import { launchClaude } from './claude.js';
 import { memoryPaths, memoryRoutine } from './memory.js';
 import { update } from './update.js';
@@ -40,6 +41,13 @@ const USAGE = `metro: run your agent on this machine
   metro agent --prepare [cli|sdk]
                   check the runner before selecting it; install the SDK runtime if needed,
                   without starting a session or connecting to chat
+  metro task submit <routine> <prompt-file> [--slot <UTC ISO timestamp>] [--dry-run]
+  metro task status [routine]
+  metro task finish <uuid> <token> completed|blocked
+                  queue work without starting a session, or read safe local task metadata;
+                  default slot is the current UTC hour; use --slot for other cadences;
+                  accepted is saved, not executed; finish awaits runner verification;
+                  --dry-run writes nothing; local authorization is not fresh owner approval
   metro memory [skill file]
                   run the memory routine once: when Claude Code transcripts changed since
                   the last run, Claude Code reads the memory skill (or the file given) and
@@ -85,6 +93,7 @@ const COMMANDS = {
     tail: () => tailEvents(process.argv.slice(3)),
     claude: () => launchClaude(process.argv.slice(3)),
     agent: () => agentSession(process.argv.slice(3)),
+    task: () => automationCommand(process.argv.slice(3)),
     memory: () => memoryRoutine(memoryPaths(process.env, process.argv[3])),
     voice: () => voiceSession(process.argv.slice(3)),
     update: () => update(process.argv.slice(3)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.277",
+  "version": "0.1.0-beta.278",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.277",
+  "version": "0.1.0-beta.278",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/node_modules/@metro-labs/core/package.json

@@ -9,6 +9,8 @@
     "./events": "./src/events.ts",
     "./is-record": "./src/is-record.ts",
     "./runner-activity": "./src/runner-activity.ts",
+    "./automation-store": "./src/automation-store.ts",
+    "./automation-types": "./src/automation-types.ts",
     "./call": "./src/call.ts",
     "./secure-fs": "./src/secure-fs.ts",
     "./version": "./src/version.ts",

package/runtime/node_modules/@metro-labs/core/src/automation-files.ts

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+import fs, { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, type Stats } from 'node:fs';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { AutomationError } from './automation-types.js';
+import { isRecord } from './is-record.js';
+
+const FILE = 'automation.sqlite';
+const SCHEMA = `
+CREATE TABLE requests (
+  uuid TEXT PRIMARY KEY NOT NULL,
+  routine TEXT NOT NULL,
+  slot INTEGER NOT NULL,
+  payload TEXT NOT NULL,
+  UNIQUE (routine, slot)
+);
+CREATE TABLE statuses (
+  uuid TEXT PRIMARY KEY NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  payload TEXT NOT NULL
+);
+CREATE TABLE resolutions (
+  uuid TEXT NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  outcome TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (uuid, outcome)
+);
+PRAGMA user_version = 1;
+`;
+
+function hasCode(error: unknown, code: string): boolean {
+  return isRecord(error) && error.code === code;
+}
+
+function metadata(path: string): Stats | null {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (hasCode(error, 'ENOENT')) return null;
+    throw error;
+  }
+}
+
+function uid(): number {
+  if (process.getuid === undefined) throw new AutomationError('unsafe-storage');
+  return process.getuid();
+}
+
+function checkDirectory(info: Stats, privateDirectory: boolean): void {
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new AutomationError('unsafe-storage');
+  if (privateDirectory) {
+    if (info.uid !== uid() || (info.mode & 0o7777) !== 0o700) throw new AutomationError('unsafe-storage');
+    return;
+  }
+  if (info.uid !== uid() && info.uid !== 0) throw new AutomationError('unsafe-storage');
+  if ((info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0) throw new AutomationError('unsafe-storage');
+}
+
+function syncDirectory(path: string): void {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function directory(root: string, create: boolean): boolean {
+  let current = parse(root).root;
+  const base = metadata(current);
+  if (base === null) throw new AutomationError('unsafe-storage');
+  checkDirectory(base, current === root);
+  for (const component of root.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, component);
+    let info = metadata(current);
+    if (info === null) {
+      if (!create) return false;
+      try {
+        mkdirSync(current, { mode: 0o700 });
+        syncDirectory(dirname(current));
+      } catch (error) {
+        if (!hasCode(error, 'EEXIST')) throw error;
+      }
+      info = metadata(current);
+    }
+    if (info === null) throw new AutomationError('unsafe-storage');
+    checkDirectory(info, current === root);
+  }
+  return true;
+}
+
+function checkFile(info: Stats, singleLink = false): void {
+  if (!info.isFile() || info.uid !== uid() || (info.mode & 0o7777) !== 0o600 || (singleLink && info.nlink !== 1)) throw new AutomationError('unsafe-storage');
+}
+
+function companions(path: string): void {
+  for (const suffix of ['-journal', '-wal', '-shm']) {
+    const info = metadata(`${path}${suffix}`);
+    if (info !== null) checkFile(info, true);
+  }
+}
+
+function sameFile(path: string, opened: Stats): void {
+  const current = metadata(path);
+  if (current === null || current.dev !== opened.dev || current.ino !== opened.ino) throw new AutomationError('unsafe-storage');
+  checkFile(current);
+}
+
+function initializeFile(path: string, fd: number): void {
+  const opened = fstatSync(fd);
+  checkFile(opened);
+  const db = new DatabaseSync(path);
+  try {
+    sameFile(path, opened);
+    db.exec('PRAGMA trusted_schema = OFF');
+    transaction(db, (database) => { database.exec(SCHEMA); });
+  } finally {
+    db.close();
+  }
+  fs.fsyncSync(fd);
+}
+
+function createFile(path: string): void {
+  if (metadata(path) !== null) return;
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    initializeFile(temporary, fd);
+    try {
+      fs.linkSync(temporary, path);
+    } catch (error) {
+      if (!hasCode(error, 'EEXIST')) throw error;
+    }
+  } finally {
+    closeSync(fd);
+    fs.unlinkSync(temporary);
+  }
+  syncDirectory(dirname(path));
+}
+
+function transaction<T>(db: DatabaseSync, action: (database: DatabaseSync) => T): T {
+  db.exec('PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; PRAGMA foreign_keys = ON; BEGIN IMMEDIATE');
+  try {
+    const result = action(db);
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+function useDatabase<T>(path: string, writable: boolean, action: (database: DatabaseSync) => T): T {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let db: DatabaseSync | undefined;
+  try {
+    const opened = fstatSync(fd);
+    checkFile(opened);
+    companions(path);
+    db = new DatabaseSync(path, { readOnly: !writable });
+    sameFile(path, opened);
+    db.exec('PRAGMA busy_timeout = 5000; PRAGMA trusted_schema = OFF');
+    if (db.prepare('PRAGMA user_version').get()?.user_version !== 1) throw new AutomationError('corrupt-storage');
+    if (writable) return transaction(db, action);
+    if (db.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete') throw new AutomationError('corrupt-storage');
+    db.exec('BEGIN');
+    try {
+      return action(db);
+    } finally {
+      db.exec('ROLLBACK');
+    }
+  } finally {
+    db?.close();
+    closeSync(fd);
+  }
+}
+
+function databasePath(root: string, writable: boolean, existingOnly: boolean): string | null {
+  const create = writable && !existingOnly;
+  const absolute = resolve(root);
+  if (!directory(absolute, create)) return null;
+  const path = join(absolute, FILE);
+  companions(path);
+  if (create) createFile(path);
+  const info = metadata(path);
+  if (info === null) {
+    if (create) throw new AutomationError('storage-unavailable');
+    return null;
+  }
+  checkFile(info);
+  return path;
+}
+
+export function validateAutomationDirectory(root: string): void {
+  try {
+    databasePath(root, false, false);
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}
+
+export function automationDatabase<T>(root: string, writable: boolean, action: (database: DatabaseSync) => T, missing: T, existingOnly = false): T {
+  try {
+    const path = databasePath(root, writable, existingOnly);
+    if (path === null) return missing;
+    const result = useDatabase(path, writable, action);
+    if (writable) {
+      companions(path);
+      syncDirectory(dirname(path));
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}

package/runtime/node_modules/@metro-labs/core/src/automation-store.ts

@@ -0,0 +1,171 @@
+import { resolve } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+import { automationDatabase, validateAutomationDirectory } from './automation-files.js';
+import {
+  AUTOMATION_REQUEST_MAX, AUTOMATION_RETENTION_MS, AutomationError, assertAutomationUuid,
+  automationRequest, automationTerminal, parseAutomationRequest, parseAutomationResolution, parseAutomationStatus,
+  type AutomationOutcome, type AutomationRequest, type AutomationResolution, type AutomationStatus,
+} from './automation-types.js';
+import { isRecord } from './is-record.js';
+
+export type { AutomationOutcome, AutomationRequest, AutomationResolution, AutomationStatus, AutomationState, AutomationUuid } from './automation-types.js';
+
+function payload<T extends { uuid: string }>(row: unknown, parse: (value: unknown) => T): T {
+  try {
+    if (!isRecord(row) || typeof row.payload !== 'string') throw new AutomationError('corrupt-storage');
+    const value: unknown = JSON.parse(row.payload);
+    const parsed = parse(value);
+    if (parsed.uuid !== row.uuid) throw new AutomationError('corrupt-storage');
+    return parsed;
+  } catch (error) {
+    throw new AutomationError('corrupt-storage', { cause: error });
+  }
+}
+
+function request(row: unknown): AutomationRequest {
+  const parsed = payload(row, parseAutomationRequest);
+  if (!isRecord(row) || parsed.routine !== row.routine || parsed.slot !== row.slot) throw new AutomationError('corrupt-storage');
+  return parsed;
+}
+
+function requests(db: DatabaseSync): AutomationRequest[] {
+  const rows = db.prepare('SELECT * FROM requests ORDER BY slot, routine LIMIT 513').all();
+  if (rows.length > AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map(request);
+}
+
+function status(db: DatabaseSync, uuid: string): AutomationStatus | null {
+  const row = db.prepare('SELECT * FROM statuses WHERE uuid = ?').get(uuid);
+  return row === undefined ? null : payload(row, parseAutomationStatus);
+}
+
+function statuses(db: DatabaseSync): AutomationStatus[] {
+  const rows = db.prepare('SELECT * FROM statuses LIMIT 513').all();
+  if (rows.length > AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map((row) => payload(row, parseAutomationStatus));
+}
+
+function resolution(row: unknown): AutomationResolution {
+  const parsed = payload(row, parseAutomationResolution);
+  if (!isRecord(row) || parsed.outcome !== row.outcome) throw new AutomationError('corrupt-storage');
+  return parsed;
+}
+
+function resolutions(db: DatabaseSync): AutomationResolution[] {
+  const rows = db.prepare('SELECT * FROM resolutions ORDER BY uuid, outcome LIMIT 1025').all();
+  if (rows.length > 2 * AUTOMATION_REQUEST_MAX) throw new AutomationError('corrupt-storage');
+  return rows.map(resolution);
+}
+
+function requireRequest(db: DatabaseSync, uuid: string): AutomationRequest {
+  const row = db.prepare('SELECT * FROM requests WHERE uuid = ?').get(uuid);
+  if (row === undefined) throw new AutomationError('unknown-request');
+  return request(row);
+}
+
+function validate(db: DatabaseSync): void {
+  const known = new Set(requests(db).map((entry) => entry.uuid));
+  for (const entry of [...statuses(db), ...resolutions(db)]) {
+    if (!known.has(entry.uuid)) throw new AutomationError('corrupt-storage');
+  }
+  if (db.prepare('PRAGMA quick_check').get()?.quick_check !== 'ok') throw new AutomationError('corrupt-storage');
+}
+
+function expiredRequests(db: DatabaseSync, cutoff: number): AutomationRequest[] {
+  const saved = new Map(statuses(db).map((entry) => [entry.uuid, entry]));
+  return requests(db).filter((entry) => {
+    const current = saved.get(entry.uuid);
+    return current !== undefined && automationTerminal(current.state) && entry.slot < cutoff && current.updatedAt < cutoff;
+  });
+}
+
+export class AutomationStore {
+  readonly root: string;
+
+  constructor(root: string, private readonly now: () => number = Date.now) {
+    this.root = resolve(root);
+  }
+
+  validate(): void {
+    validateAutomationDirectory(this.root);
+  }
+
+  recover(): void {
+    automationDatabase(this.root, true, validate, undefined, true);
+  }
+
+  submit(routine: string, slot: number, prompt: string): AutomationRequest {
+    const proposed = automationRequest(routine, slot, prompt, this.now());
+    return automationDatabase(this.root, true, (db) => {
+      const accepted = automationRequest(routine, slot, prompt, this.now());
+      const existing = requests(db);
+      const found = existing.find((entry) => entry.routine === routine && entry.slot === slot);
+      if (found !== undefined) {
+        if (found.prompt !== prompt) throw new AutomationError('conflict');
+        return found;
+      }
+      if (existing.length >= AUTOMATION_REQUEST_MAX) throw new AutomationError('full');
+      db.prepare('INSERT INTO requests (uuid, routine, slot, payload) VALUES (?, ?, ?, ?)')
+        .run(accepted.uuid, routine, slot, JSON.stringify(accepted));
+      return accepted;
+    }, proposed);
+  }
+
+  requests(): AutomationRequest[] {
+    return automationDatabase(this.root, false, requests, []);
+  }
+
+  status(uuid: string): AutomationStatus | null {
+    assertAutomationUuid(uuid);
+    return automationDatabase(this.root, false, (db) => status(db, uuid), null);
+  }
+
+  statuses(): AutomationStatus[] {
+    return automationDatabase(this.root, false, statuses, []);
+  }
+
+  saveStatus(value: AutomationStatus): void {
+    const parsed = parseAutomationStatus(value);
+    automationDatabase(this.root, true, (db) => {
+      requireRequest(db, parsed.uuid);
+      db.prepare('INSERT INTO statuses (uuid, payload) VALUES (?, ?) ON CONFLICT(uuid) DO UPDATE SET payload = excluded.payload')
+        .run(parsed.uuid, JSON.stringify(parsed));
+    }, undefined);
+  }
+
+  finish(uuid: string, token: string, outcome: AutomationOutcome): AutomationResolution {
+    const proposed = parseAutomationResolution({ uuid, token, outcome, createdAt: this.now() });
+    const current = this.status(uuid);
+    if (current === null) throw new AutomationError('unknown-request');
+    if (current.token !== token) throw new AutomationError('invalid-token');
+    return automationDatabase(this.root, true, (db) => {
+      requireRequest(db, uuid);
+      if (status(db, uuid)?.token !== token) throw new AutomationError('invalid-token');
+      const row = db.prepare('SELECT * FROM resolutions WHERE uuid = ? AND outcome = ?').get(uuid, outcome);
+      if (row !== undefined) {
+        const found = resolution(row);
+        if (found.token !== token) throw new AutomationError('invalid-token');
+        return found;
+      }
+      db.prepare('INSERT INTO resolutions (uuid, outcome, payload) VALUES (?, ?, ?)').run(uuid, outcome, JSON.stringify(proposed));
+      return proposed;
+    }, proposed);
+  }
+
+  resolutions(): AutomationResolution[] {
+    return automationDatabase(this.root, false, resolutions, []);
+  }
+
+  prune(): number {
+    const cutoff = this.now() - AUTOMATION_RETENTION_MS;
+    if (!Number.isSafeInteger(cutoff)) throw new AutomationError('invalid-slot');
+    const eligible = automationDatabase(this.root, false, (db) => expiredRequests(db, cutoff).length > 0, false);
+    if (!eligible) return 0;
+    return automationDatabase(this.root, true, (db) => {
+      validate(db);
+      const expired = expiredRequests(db, cutoff);
+      for (const entry of expired) db.prepare('DELETE FROM requests WHERE uuid = ?').run(entry.uuid);
+      return expired.length;
+    }, 0);
+  }
+}

package/runtime/node_modules/@metro-labs/core/src/automation-types.ts

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from './is-record.js';
+
+export const AUTOMATION_PROMPT_MAX = 64 * 1024;
+const PROMPT_JSON_MAX = 128 * 1024 + 2;
+export const AUTOMATION_REQUEST_MAX = 512;
+export const AUTOMATION_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const AUTOMATION_ROUTINE_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const STATES = ['dispatched', 'consumed', 'awaiting-completion', 'completed', 'failed', 'interrupted', 'coalesced', 'cancelled'] as const;
+const DETAILS = ['sdk-completed', 'sdk-failed', 'runner-interrupted', 'newer-slot', 'owner-cancelled', 'worker-blocked', 'worker-completed'] as const;
+const TERMINAL = new Set<AutomationState>(['completed', 'coalesced', 'cancelled']);
+const ERRORS = {
+  'invalid-routine': 'Routine must be a lowercase name of at most 64 characters.',
+  'invalid-slot': 'Slot must be an integer timestamp within the past seven days or next five minutes.',
+  'invalid-prompt': 'Prompt must be text no larger than 64 KiB and 128 KiB plus quotes when JSON-encoded.',
+  'invalid-uuid': 'Automation identifier must be a canonical UUID.',
+  'invalid-request': 'Automation request is invalid.',
+  'invalid-status': 'Automation status is invalid.',
+  'invalid-resolution': 'Automation completion receipt is invalid.',
+  conflict: 'This routine and slot already have a different prompt.',
+  full: 'Automation queue is full. Only old terminal requests may be pruned.',
+  'unknown-request': 'Automation request does not exist.',
+  'invalid-token': 'Completion token does not match the dispatched request.',
+  'unsafe-storage': 'Automation storage must be private, owned by this user, and free of symlinks.',
+  'corrupt-storage': 'Automation storage is corrupt. No requests were discarded.',
+  'storage-unavailable': 'Automation storage is unavailable. No acceptance is confirmed.',
+} as const;
+
+export type AutomationUuid = `${string}-${string}-${string}-${string}-${string}`;
+export type AutomationState = (typeof STATES)[number];
+export type AutomationDetail = (typeof DETAILS)[number];
+export type AutomationOutcome = 'completed' | 'blocked';
+export type AutomationErrorCode = keyof typeof ERRORS;
+
+export class AutomationError extends Error {
+  constructor(readonly code: AutomationErrorCode, options?: ErrorOptions) {
+    super(ERRORS[code], options);
+    this.name = 'AutomationError';
+  }
+}
+
+export interface AutomationRequest {
+  version: 1;
+  routine: string;
+  slot: number;
+  uuid: AutomationUuid;
+  createdAt: number;
+  prompt: string;
+  digest: string;
+}
+
+export interface AutomationStatus {
+  uuid: AutomationUuid;
+  state: AutomationState;
+  updatedAt: number;
+  token: AutomationUuid;
+  detail?: AutomationDetail;
+}
+
+export interface AutomationResolution {
+  uuid: AutomationUuid;
+  token: AutomationUuid;
+  outcome: AutomationOutcome;
+  createdAt: number;
+}
+
+export function assertRoutine(routine: unknown): asserts routine is string {
+  if (typeof routine !== 'string' || !AUTOMATION_ROUTINE_RE.test(routine)) throw new AutomationError('invalid-routine');
+}
+
+export function assertAutomationUuid(uuid: unknown): asserts uuid is AutomationUuid {
+  if (typeof uuid !== 'string' || !UUID_RE.test(uuid)) throw new AutomationError('invalid-uuid');
+}
+
+function timestamp(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 8_640_000_000_000_000;
+}
+
+function promptValid(value: unknown): value is string {
+  return typeof value === 'string' && Buffer.byteLength(value, 'utf8') <= AUTOMATION_PROMPT_MAX && Buffer.byteLength(JSON.stringify(value), 'utf8') <= PROMPT_JSON_MAX;
+}
+
+function validSlot(slot: number, now: number): boolean {
+  return slot >= now - AUTOMATION_RETENTION_MS && slot <= now + 300_000;
+}
+
+function hash(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function requestUuid(routine: string, slot: number): AutomationUuid {
+  const bytes = createHash('sha256').update(`${routine}\n${slot}`).digest();
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x80;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = bytes.subarray(0, 16).toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function automationRequest(routine: string, slot: number, prompt: string, now = Date.now()): AutomationRequest {
+  assertRoutine(routine);
+  if (!timestamp(now) || !timestamp(slot) || !validSlot(slot, now)) throw new AutomationError('invalid-slot');
+  if (!promptValid(prompt)) throw new AutomationError('invalid-prompt');
+  return { version: 1, routine, slot, uuid: requestUuid(routine, slot), createdAt: now, prompt, digest: hash(prompt) };
+}
+
+function fields(raw: Record<string, unknown>, required: string[], optional: string[] = []): boolean {
+  return required.every((key) => Object.hasOwn(raw, key)) && Object.keys(raw).every((key) => required.includes(key) || optional.includes(key));
+}
+
+export function parseAutomationRequest(raw: unknown): AutomationRequest {
+  if (!isRecord(raw) || !fields(raw, ['version', 'routine', 'slot', 'uuid', 'createdAt', 'prompt', 'digest'])) throw new AutomationError('invalid-request');
+  assertRoutine(raw.routine);
+  assertAutomationUuid(raw.uuid);
+  if (raw.version !== 1 || !timestamp(raw.slot) || !timestamp(raw.createdAt) || !promptValid(raw.prompt)) throw new AutomationError('invalid-request');
+  if (!validSlot(raw.slot, raw.createdAt) || raw.uuid !== requestUuid(raw.routine, raw.slot) || raw.digest !== hash(raw.prompt)) throw new AutomationError('invalid-request');
+  return { version: 1, routine: raw.routine, slot: raw.slot, uuid: raw.uuid, createdAt: raw.createdAt, prompt: raw.prompt, digest: raw.digest };
+}
+
+export function parseAutomationStatus(raw: unknown): AutomationStatus {
+  if (!isRecord(raw) || !fields(raw, ['uuid', 'state', 'updatedAt', 'token'], ['detail'])) throw new AutomationError('invalid-status');
+  assertAutomationUuid(raw.uuid);
+  assertAutomationUuid(raw.token);
+  const state = STATES.find((entry) => entry === raw.state);
+  if (state === undefined || !timestamp(raw.updatedAt)) throw new AutomationError('invalid-status');
+  const detail = DETAILS.find((entry) => entry === raw.detail);
+  if (raw.detail !== undefined && detail === undefined) throw new AutomationError('invalid-status');
+  return { uuid: raw.uuid, state, updatedAt: raw.updatedAt, token: raw.token, ...(detail === undefined ? {} : { detail }) };
+}
+
+export function parseAutomationResolution(raw: unknown): AutomationResolution {
+  if (!isRecord(raw) || !fields(raw, ['uuid', 'token', 'outcome', 'createdAt'])) throw new AutomationError('invalid-resolution');
+  assertAutomationUuid(raw.uuid);
+  assertAutomationUuid(raw.token);
+  if (!timestamp(raw.createdAt) || (raw.outcome !== 'completed' && raw.outcome !== 'blocked')) throw new AutomationError('invalid-resolution');
+  return { uuid: raw.uuid, token: raw.token, outcome: raw.outcome, createdAt: raw.createdAt };
+}
+
+export function automationTerminal(state: AutomationState): boolean {
+  return TERMINAL.has(state);
+}

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.277"
+  "version": "0.1.0-beta.278"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/package.json

@@ -9,6 +9,8 @@
     "./events": "./src/events.ts",
     "./is-record": "./src/is-record.ts",
     "./runner-activity": "./src/runner-activity.ts",
+    "./automation-store": "./src/automation-store.ts",
+    "./automation-types": "./src/automation-types.ts",
     "./call": "./src/call.ts",
     "./secure-fs": "./src/secure-fs.ts",
     "./version": "./src/version.ts",