rome agentic OS

57export interface AppArtifactSummary {
58  name: string;
59  description: string;
60  /** Diagnostic for a declared artifact that failed to load. Consumers must surface it. */
61  loadError?: string;
62}
63
64export interface AppArtifactDetails {
65  agents: AppArtifactSummary[];
66  actions: AppArtifactSummary[];
67  skills: AppArtifactSummary[];
68  hooks: AppArtifactSummary[];
69}
70
71/** Non-binding routing hint from an app manifest. Channel contract: docs/architecture/channels.md. */
72export interface SuggestedChannelBinding {
73  channel: "discord" | "telegram" | "whatsapp" | "wechat" | "webchat" | "feishu";
74  agent: string;
75  reason?: string;
76}
77
78export interface AppSpec {
79  source: SpecSource;
80  enabled: boolean;
81}
82
83export interface InstalledAppCard {
84  id: string;
85  version: string;
86  description: string;
87  displayName: string;
88  status: RomeAppRuntimeStatus;
89  phase: AppViewState;
90  error?: string;
91  hasFrontend: boolean;
92  href: string | null;
93  fullHref: string | null;
94  capabilities: string[];
95  capabilityDetails: AppArtifactDetails;
96  isEnabled: boolean;
97  canToggle: boolean;
98  canUninstall: boolean;
99  /** Projection of the installed app.yaml flag. Missing means false. */
100  includeSource?: boolean;
101  /** UI capability hint only; the publish endpoint still enforces store policy. */
102  canPublish: boolean;
103  accessMode: AppAccessMode;
104  isPublic: boolean;
105  cloudAllowedEmails: string[];
106  canManagePublicAccess: boolean;
107  /** Authoritative installed source, suitable for a re-install or upgrade request. */
108  source: SpecSource;
109  /**
110   * Project-root-relative path of the app's editable source workspace. This is
111   * present only when the installed source is a workspace inside Rome's
112   * projects tree, and can be passed directly to the new-chat flow.
113   */
114  projectPath: string | null;
115  origin: AppOrigin;
116  /** Root-relative icon URL, or `null` when the manifest declares no icon. */
117  iconUrl: string | null;
118  /** Optional on the wire; consumers must default to `[]`. */
119  suggestedChannelBindings?: SuggestedChannelBinding[];
120}

27const SALT_QUERY = /\?v=[^&]*$/;
28
29function isSaltableUrl(url: string): boolean {
30  const path = url.split("?")[0];
31  return path.endsWith(".js") || path.endsWith(".mjs");
32}
33
34registerHooks({
35  resolve(specifier, context, nextResolve) {
36    if (specifier.startsWith("file:") && SALT_QUERY.test(specifier) && isSaltableUrl(specifier)) {
37      return { url: specifier, format: "module", shortCircuit: true };
38    }
39    const result = nextResolve(specifier, context);
40    if (
41      (specifier.startsWith("./") || specifier.startsWith("../")) &&
42      context.parentURL !== undefined &&
43      SALT_QUERY.test(context.parentURL) &&
44      result.url.startsWith("file:") &&
45      !result.url.includes("?") &&
46      isSaltableUrl(result.url)
47    ) {
48      const salt = new URL(context.parentURL).searchParams.get("v");
49      if (salt) return { url: `${result.url}?v=${salt}`, format: "module", shortCircuit: true };
50    }
51    return result;
52  },
53  load(url, context, nextLoad) {
54    if (url.startsWith("file:") && SALT_QUERY.test(url) && isSaltableUrl(url)) {
55      const cleanUrl = new URL(url);
56      cleanUrl.search = "";
57      return {
58        format: "module",
59        source: readFileSync(fileURLToPath(cleanUrl)),
60        shortCircuit: true,
61      };
62    }
63    return nextLoad(url, context);
64  },
65});

101export async function resolveModuleEntryPath(baseDir: string, entry?: string): Promise<string> {
102  const absoluteBaseDir = resolve(baseDir);
103  const specifier = entry ?? "./index";
104  const result = await sharedResolver.async(absoluteBaseDir, specifier);
105  if (!result.path) {
106    throw new Error(
107      `No entry module found for "${baseDir}" (resolving "${specifier}"): ${result.error ?? "no path returned"}`,
108    );
109  }
110  const [realBaseDir, realEntryPath] = await Promise.all([
111    realpath(absoluteBaseDir),
112    realpath(result.path),
113  ]);
114  const relativeEntryPath = relative(realBaseDir, realEntryPath);
115  if (relativeEntryPath.startsWith("..") || isAbsolute(relativeEntryPath)) {
116    throw new Error(`Invalid entry path "${specifier}" for ${baseDir}: escapes base dir`);
117  }
118  return result.path;
119}
120
121// App modules can read process.env at module scope, and the file-identity
122// buster below cannot see an environment change. Bumping this epoch salts the
123// cache key so every subsequent import re-evaluates module scope against the
124// current environment (app keys do this on save/delete). Each bump strands the
125// previously imported instances in the ESM cache — the same cost as an app
126// upgrade changing mtime — bounded by how often a guardian edits keys.
127let envEpoch = 0;
128
129export function bumpModuleEnvEpoch(): void {
130  envEpoch++;
131}
132
133export async function importModuleWithCacheBuster(path: string): Promise<Record<string, unknown>> {
134  const fileStat = await stat(path);
135  const cacheBuster = `${Math.trunc(fileStat.mtimeMs)}-${fileStat.size}-e${envEpoch}`;
136  const url = `${pathToFileURL(path).href}?v=${cacheBuster}`;
137  return await import(url);
138}

127function createLazyAppAction(
128  record: AppActionRecord,
129  catalog: AppCatalog,
130  deps: Record<string, unknown>,
131  services: AppActionServices,
132): Action {
133  let actionPromise: Promise<Action> | null = null;
134
135  const load = async (): Promise<Action> => {
136    if (!actionPromise) {
137      actionPromise = instantiateActionFromDirectory(
138        record.config,
139        record.directory,
140        createAppActionRuntimeDeps(record, catalog, deps, services),
141      ).catch((err) => {
142        actionPromise = null;
143        throw err;
144      });
145    }
146    return actionPromise;
147  };
148
149  return {
150    config: record.config,
151    async execute(args: Record<string, unknown>, context?: ActionExecutionContext) {
152      const action = await load();
153      return action.execute(args, context);
154    },
155    async preview(args: Record<string, unknown>) {
156      const action = await load();
157      return action.preview?.(args);
158    },
159  };

5/**
6 * Owns the stored-key slice of `process.env`. Two invariants:
7 *
8 * - The real process environment always wins. A name that already had a value
9 *   before injection is never overwritten — operator config (env files, CI,
10 *   container env) cannot be shadowed from the dashboard. Such keys are
11 *   reported as overridden instead of silently going live.
12 * - Only names this injector set are ever deleted or scrubbed. It tracks its
13 *   own writes, so removing a stored key can never unset an operator-set var
14 *   that happens to share the name.
15 */
16export class AppKeyInjector {
17  private injected = new Set<string>();
18  private overridden = new Set<string>();
19
20  constructor(private env: NodeJS.ProcessEnv = process.env) {}
21
22  /** Applies a stored key. Returns true when the value went live, false when a
23   * pre-existing environment value kept precedence. */
24  apply(name: string, value: string): boolean {
25    if (!this.injected.has(name) && this.env[name] !== undefined) {
26      this.overridden.add(name);
27      logger.warn(
28        `App key ${name} is overridden by the process environment; the stored value is not live`,
29      );
30      return false;
31    }
32    this.env[name] = value;
33    this.injected.add(name);
34    return true;
35  }
36
37  /** Removes a stored key from the environment, only if this injector set it.
38   * Returns true when the environment actually changed. */
39  remove(name: string): boolean {
40    this.overridden.delete(name);
41    if (!this.injected.has(name)) return false;
42    delete this.env[name];
43    this.injected.delete(name);
44    return true;
45  }
46
47  isOverridden(name: string): boolean {
48    return this.overridden.has(name);
49  }
50}

21export const APP_KEY_MAX_NAME_LENGTH = 64;
22export const APP_KEY_MAX_LABEL_LENGTH = 120;
23export const APP_KEY_MAX_VALUE_LENGTH = 32768;
24
25const NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
26
27// An app key lands in `process.env`, so a name that collides with platform
28// configuration could reroute the database, the API ports, or an upstream
29// credential. Config env names are only expressed as inline `env.X` reads in
30// core's `config.ts` (`envToRawConfig`) — there is no enumerable schema to
31// check against — so this list carries every prefix family the platform
32// consumes plus the ambient OS names a child process relies on.
33const RESERVED_PREFIXES = [
34  "ROME_",
35  "NODE_",
36  "NPM_",
37  "PNPM_",
38  "PANTHEON_",
39  "INTERNAL_API_",
40  "RELAY_",
41  "STATSIG_",
42  "FEATURE_GATE_",
43  "OTEL_",
44  "SQLITE_",
45  "POSTGRES_",
46  "DATABASE_",
47  "WEB_",
48  "LINKEDIN_",
49  "SENTINEL_",
50  "ANTHROPIC_",
51  "DOCKERHUB_",
52  "CLICKHOUSE_",
53  "AWS_",
54  "SSH_",
55  "NEXT_",
56];
57
58const RESERVED_NAMES = new Set([
59  "PATH",
60  "HOME",
61  "USER",
62  "LOGNAME",
63  "SHELL",
64  "TMPDIR",
65  "TMP",
66  "TEMP",
67  "PWD",
68  "LANG",
69  "LC_ALL",
70  "TZ",
71  "TERM",
72  "HOSTNAME",
73  "EDITOR",
74  "CI",
75  "LOG_LEVEL",
76  "UPDATES_DOMAIN",
77]);
78
79/** Returns a human-readable rejection reason, or null when the name is usable. */
80export function appKeyNameError(name: string): string | null {
81  if (name.length === 0) return "Name is required.";
82  if (name.length > APP_KEY_MAX_NAME_LENGTH) {
83    return `Name must be at most ${APP_KEY_MAX_NAME_LENGTH} characters.`;
84  }
85  if (!NAME_PATTERN.test(name)) {
86    return "Name must use only uppercase letters, digits, and underscores, and start with a letter.";
87  }
88  if (RESERVED_NAMES.has(name)) {
89    return `${name} is reserved by Rome. Pick a different name.`;
90  }
91  const prefix = RESERVED_PREFIXES.find((p) => name.startsWith(p));
92  if (prefix) {
93    return `Names starting with ${prefix} are reserved by Rome. Pick a different name.`;
94  }
95  return null;
96}

1import "./styles.css";
2import { useCallback, useState } from "react";
3import { startChat, type RomeAppBootstrap } from "@rome-os/app-web-sdk";
4
5const EXAMPLE_PROMPTS = [
6  "Every morning, summarize my unread emails and post the digest to my chat.",
7  "When I save a link to my reading list, fetch the article and add a short summary.",
8];
9
10// The app is a front door: describing an automation opens a fresh guardian chat
11// with that message under the `design-workflow` skill, which shapes it into a
12// short spec, gets the guardian's approval, and builds the workflow — all in that
13// one conversation. There is no panel to mirror, so the page is just the launcher.
14export default function App({ bootstrap: _bootstrap }: { bootstrap: RomeAppBootstrap }) {
15  const [draft, setDraft] = useState("");
16  const [starting, setStarting] = useState(false);
17  const [error, setError] = useState<string | null>(null);
18
19  const start = useCallback(async () => {
20    const message = draft.trim();
21    if (!message || starting) return;
22    setStarting(true);
23    setError(null);
24    try {
25      await startChat({ message, skillName: "design-workflow" });
26      // startChat navigates to the new chat on success; no further work here.
27    } catch {
28      setStarting(false);
29      setError("Couldn't start a chat just now — try again.");
30    }
31  }, [draft, starting]);
32
33  return (
34    <div className="ws-root">
35      <div className="ws-frontdoor">
36        <h1>Build a workflow</h1>
37        <p className="ws-lede">
38          Describe an automation in plain language. Your guardian shapes it into a short spec you
39          approve, then builds it into a runnable workflow — all in one conversation.
40        </p>
41        <textarea
42          className="ws-input"
43          rows={3}
44          placeholder="e.g. Every morning, summarize my unread emails and post the digest to my chat."
45          value={draft}
46          onChange={(e) => setDraft(e.target.value)}
47          disabled={starting}
48        />
49        <div className="ws-cta-row">
50          <button
51            className="ws-cta"
52            onClick={() => void start()}
53            disabled={!draft.trim() || starting}
54          >
55            {starting ? "Starting…" : "Design this workflow"}
56          </button>
57        </div>
58        {error && <p className="ws-error-line">{error}</p>}
59        <div className="ws-examples">
60          <span className="ws-examples-label">Try one of these</span>
61          {EXAMPLE_PROMPTS.map((p) => (
62            <button
63              key={p}
64              type="button"
65              className="ws-example"
66              onClick={() => setDraft(p)}
67              disabled={starting}
68            >
69              {p}
70            </button>
71          ))}
72        </div>
73      </div>
74    </div>
75  );
76}

14## Phase 1 — Shape the idea into a spec
15
16Turn what the guardian said into a short, plain-language spec they can read and
17sign off on. The spec is the thing they approve, so write it for a non-technical
18reader — what the automation *does*, not how it's coded. Use this shape:
19
20> **Trigger** — what kicks it off (a schedule, an event, a "run now").
21> **Steps** — the ordered things it does, one short verb phrase each
22> ("fetch my unread emails", "summarize them", "post the digest to my chat").
23> **Decisions** — any branch ("if the total is over $5k, escalate; otherwise file
24> it"), stated as plain conditions.
25> **Per-item work** — anything done "for each" of a list ("for each ticket, rate
26> its severity").
27> **Delivers** — the final step that sends, posts, saves, or shows the result.
28
29Hold these disciplines while you shape it — they decide whether the spec is real:
30
31- **Ask the guardian for facts only they can supply; never invent them.** A
32  threshold amount, a recipient, a channel, which account, which event fires the
33  trigger — a made-up "$5,000" looks authoritative and gets approved by accident.
34  When a fact like this is missing, ask for it in your reply rather than guessing.
35- **Resolve design questions in conversation, not in the spec.** Anything that
36  changes the *shape* — whether to branch, what to do per item — gets settled with
37  the guardian before you present the spec, not parked as an open question in it.
38- **Every workflow must deliver.** A spec that only fetches and computes, with no
39  step that sends/posts/saves/shows a result, has no destination and is never
40  finished. If the guardian didn't say where the result goes, that's a fact to ask
41  for (see above).
42- **Don't let vague quantifiers pass.** "the top labs", "the latest news", "key
43  themes", "top outlets" each hide a fact — how many, which sources, what time
44  window. If it changes what the automation does, pin it down with the guardian.
45- **Keep it statically structured.** The full space of what it does must be
46  knowable before it runs: ordered steps, parallel work, a decision, or bounded
47  per-item fan-out. No "keep polling until…", no unbounded loops.
48
49Keep the spec itself conversational and free of technical artifacts — no JSON, no
50flow chart, no node/combinator vocabulary. Talk about what it will *do*.
51
52## Phase 2 — Get approval
53
54Present the spec and ask the guardian to approve it or tell you what to change.
55Make the ask explicit ("Want me to build this, or change anything first?"). If
56they ask for a change, revise the spec and ask again. Build **only** after a clear
57yes — don't start scaffolding on a maybe.
58
59## Phase 3 — Build it
60
61On approval, build the workflow into a new, runnable Rome app. **Load the
62`coding:workflow_creation` skill and follow it end to end** — it owns the real work:
63deriving the control flow, scaffolding the `workflow` template, authoring
64`src/workflow/definition.ts` in plain TypeScript (`await`/`if`/`for`/`Promise.all`),
65the `system:summon` discipline for generative steps, the `connector:connector_proxy` discipline for
66SaaS calls, the `ctx.dryRun` guard on every write, the display envelope, the web
67surface, and the install. Translate the approved spec into its control flow
68faithfully — don't redesign the automation while coding it.

92export interface SubagentStartBlock extends TraceBlockBase {
93  type: "subagent_start";
94  toolUseId: string;
95  agentName: string;
96  input: unknown;
97  sessionId: string;
98  turnId: string;
99  startedAt?: string;
100}
101
102export type SubagentResultBlock =
103  | (TraceBlockBase & {
104      type: "subagent_result";
105      toolUseId: string;
106      agentName: string;
107      sessionId: string;
108      turnId: string;
109      status: "completed";
110      output: unknown;
111      endedAt?: string;
112    })
113  | (TraceBlockBase & {
114      type: "subagent_result";
115      toolUseId: string;
116      agentName: string;
117      sessionId: string;
118      turnId: string;
119      status: "failed" | "cancelled";
120      error: { message: string; code?: string };
121      endedAt?: string;
122    });

124export interface TraceTokenUsage {
125  cacheReadTokens: number;
126  cacheWriteTokens: number;
127  inputTokens: number;
128  outputTokens: number;
129}
130
131export interface TraceContextUsage {
132  usedTokens: number;
133  windowTokens?: number;
134  remainingTokens?: number;
135}
136
137/** Read-time usage grouped by the provider/model that produced it. */
138export interface TraceModelUsage {
139  provider: string;
140  model: string;
141  usage: TraceTokenUsage;
142  costUsd?: number;
143  runCount: number;
144}
145
146export interface TraceAccounting {
147  provider: string;
148  model: string;
149  usage: TraceTokenUsage;
150  context?: TraceContextUsage;
151  costUsd?: number;
152  numTurns?: number;
153  stopReason?: string;
154  durationMs?: number;
155  rawUsage?: Record<string, unknown>;
156  /** Number of descendant subagent runs included in `usage` and `costUsd`.
157   *  Derived only for trace reads; never persisted in canonical trace blocks. */
158  includedSubagentCount?: number;
159  /** Main + descendant usage grouped by provider/model. Like
160   *  `includedSubagentCount`, this is derived only on trace reads. */
161  usageByModel?: TraceModelUsage[];
162}

19  it("re-evaluates the relative-import graph only after an epoch bump", async () => {
20    const dir = await mkdtemp(join(tmpdir(), "module-loader-epoch-"));
21    try {
22      // The env read lives in an imported helper, not the entry: the resolve
23      // hook must propagate the entry's cache salt onto the relative import
24      // or the helper stays cached across epochs.
25      await writeFile(
26        join(dir, "config.js"),
27        `export const captured = process.env.${TEST_KEY} ?? "unset";\n`,
28        "utf-8",
29      );
30      await writeFile(join(dir, "entry.js"), `export { captured } from "./config.js";\n`, "utf-8");
31
32      const loaderUrl = pathToFileURL(
33        resolve(dirname(fileURLToPath(import.meta.url)), "module-loader.ts"),
34      ).href;
35      const probePath = join(dir, "probe.mjs");
36      await writeFile(
37        probePath,
38        `
39import { bumpModuleEnvEpoch, importModuleWithCacheBuster } from ${JSON.stringify(loaderUrl)};
40
41const entry = process.argv[2];
42const before = await importModuleWithCacheBuster(entry);
43process.env.${TEST_KEY} = "v1";
44const withoutBump = await importModuleWithCacheBuster(entry);
45bumpModuleEnvEpoch();
46const after = await importModuleWithCacheBuster(entry);
47console.log(JSON.stringify({
48  before: before.captured,
49  withoutBump: withoutBump.captured,
50  after: after.captured,
51}));
52`,
53        "utf-8",
54      );
55
56      // Run under tsx — both the `source` container mode and the forked action
57      // workers in dev use it, and it is the loader that normalizes queries
58      // away without the short-circuit hook. (Plain node, the `compiled` mode,
59      // exercises the same hooks minus the tsx chain.)
60      const coreRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
61      const { stdout } = await execFileAsync(
62        process.execPath,
63        ["--import", "tsx", probePath, join(dir, "entry.js")],
64        { cwd: coreRoot },
65      );
66      const lines = stdout.trim().split("\n");
67      expect(JSON.parse(lines[lines.length - 1])).toEqual({
68        before: "unset",
69        withoutBump: "unset",
70        after: "v1",
71      });
72    } finally {
73      await rm(dir, { recursive: true, force: true });
74    }
75  }, 30_000);