forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

package/templates/agent-workroom/README.md

@@ -0,0 +1,34 @@
+# __FORGE_APP_TITLE__
+
+An agent-native ForgeOS workroom. It is not a chat app. Codex, Claude Code, or
+Cursor work in this directory, while the UI shows the app preview, terminal-like
+agent signals, generated freshness, diff focus, checks, and handoff evidence
+collected by ForgeOS.
+
+## Run
+
+```bash
+__PACKAGE_MANAGER__ install
+__PACKAGE_MANAGER__ run generate
+__PACKAGE_MANAGER__ run dev
+```
+
+The workroom runs on the Forge web port. The app being built should normally run
+on the next port, for example `http://127.0.0.1:5174`.
+
+## Attach to Studio
+
+```bash
+forge studio attach . --target codex --preview-port 5174
+forge agent doctor --target codex
+```
+
+Agent hooks can feed the room through ForgeOS commands or `forge agent ingest`.
+
+The browser does not chat with an AI model. It observes:
+
+- the app preview, usually on `http://127.0.0.1:5174`;
+- hook or ingest events from the external code agent;
+- authored-vs-generated diff focus;
+- generated artifact state (`fresh`, `regenerated`, or `stale-risk`);
+- verification evidence from `forge check` / `forge verify agent`.

package/templates/agent-workroom/forge.config.ts

@@ -0,0 +1,3 @@
+export default {
+  sourceRoots: ["src"],
+};

package/templates/agent-workroom/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__FORGE_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "web"
+  ],
+  "packageManager": "__PACKAGE_MANAGER_SPEC__",
+  "scripts": {
+    "forge": "forge",
+    "generate": "forge generate",
+    "check": "forge check",
+    "verify": "forge verify agent",
+    "dev": "forge dev",
+    "dev:api": "forge dev --api-only",
+    "dev:web": "cd web && __PACKAGE_MANAGER__ run dev",
+    "typecheck": "tsc --noEmit && cd web && __PACKAGE_MANAGER__ run typecheck"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "forge": "__FORGE_PACKAGE_SPEC__"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.3"
+  },
+  "forge": {
+    "template": "agent-workroom",
+    "sourceRoots": [
+      "src"
+    ]
+  }
+}

package/templates/agent-workroom/src/actions/indexAgentSignal.ts

@@ -0,0 +1,10 @@
+import { action } from "forge/server";
+
+export const indexAgentSignal = action({
+  event: "agent.signal.recorded",
+  handler: async (_ctx, event) => ({
+    ok: true,
+    indexed: true,
+    event,
+  }),
+});

package/templates/agent-workroom/src/commands/openWorkroom.ts

@@ -0,0 +1,61 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+export const openWorkroom = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      appName?: unknown;
+      appPath?: unknown;
+      previewUrl?: unknown;
+      previewStatus?: unknown;
+      previewStatusReason?: unknown;
+      agent?: unknown;
+      objective?: unknown;
+      generatedState?: unknown;
+      generatedChangedFiles?: unknown;
+      authoredFiles?: unknown;
+      generatedFiles?: unknown;
+      authoredDiffCommand?: unknown;
+      generatedDiffCommand?: unknown;
+      terminalCommand?: unknown;
+      terminalCwd?: unknown;
+    };
+    const now = new Date().toISOString();
+    const session = await ctx.db.agentSessions.insert({
+      appName: text(input.appName, "__FORGE_APP_TITLE__"),
+      appPath: text(input.appPath, "."),
+      previewUrl: text(input.previewUrl, "http://127.0.0.1:5174"),
+      previewStatus: text(input.previewStatus, "not-checked"),
+      previewStatusReason: text(input.previewStatusReason, "Preview has not been probed yet."),
+      agent: text(input.agent, "codex"),
+      status: "observing",
+      objective: text(input.objective, "External agent development session"),
+      generatedState: text(input.generatedState, "fresh"),
+      generatedChangedFiles: count(input.generatedChangedFiles),
+      authoredFiles: count(input.authoredFiles),
+      generatedFiles: count(input.generatedFiles),
+      authoredDiffCommand: text(input.authoredDiffCommand, 'git diff -- . ":(exclude)src/forge/_generated/**" ":(exclude)forge.lock"'),
+      generatedDiffCommand: text(input.generatedDiffCommand, "git diff -- src/forge/_generated forge.lock"),
+      terminalCommand: text(input.terminalCommand, "codex"),
+      terminalCwd: text(input.terminalCwd, "."),
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.emit("workroom.opened", {
+      sessionId: session.id,
+      appName: session.appName,
+      agent: session.agent,
+    });
+
+    return session;
+  },
+});

package/templates/agent-workroom/src/commands/recordAgentSignal.ts

@@ -0,0 +1,119 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function optionalCount(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+export const recordAgentSignal = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      sessionId?: unknown;
+      source?: unknown;
+      kind?: unknown;
+      title?: unknown;
+      detail?: unknown;
+      filesChanged?: unknown;
+      status?: unknown;
+      previewStatus?: unknown;
+      previewStatusReason?: unknown;
+      generatedState?: unknown;
+      generatedChangedFiles?: unknown;
+      authoredFiles?: unknown;
+      generatedFiles?: unknown;
+      authoredDiffCommand?: unknown;
+      generatedDiffCommand?: unknown;
+      terminalCommand?: unknown;
+      terminalCwd?: unknown;
+    };
+    let session =
+      typeof input.sessionId === "string" && input.sessionId.trim().length > 0
+        ? await ctx.db.agentSessions.get(input.sessionId)
+        : null;
+    if (!session) {
+      const sessions = await ctx.db.agentSessions.all();
+      session = sessions
+        .slice()
+        .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))[0] ?? null;
+    }
+    if (!session) {
+      const createdAt = new Date().toISOString();
+      session = await ctx.db.agentSessions.insert({
+        appName: "__FORGE_APP_TITLE__",
+        appPath: ".",
+        previewUrl: "http://127.0.0.1:5174",
+        previewStatus: "not-checked",
+        previewStatusReason: "Preview has not been probed yet.",
+        agent: "codex",
+        status: "observing",
+        objective: "External agent development session",
+        generatedState: "fresh",
+        generatedChangedFiles: 0,
+        authoredFiles: 0,
+        generatedFiles: 0,
+        authoredDiffCommand: 'git diff -- . ":(exclude)src/forge/_generated/**" ":(exclude)forge.lock"',
+        generatedDiffCommand: "git diff -- src/forge/_generated forge.lock",
+        terminalCommand: "codex",
+        terminalCwd: ".",
+        createdAt,
+        updatedAt: createdAt,
+      });
+    }
+    if (!session) {
+      throw new Error("session not found");
+    }
+
+    const now = new Date().toISOString();
+    const signal = await ctx.db.agentSignals.insert({
+      sessionId: session.id,
+      source: text(input.source, session.agent),
+      kind: text(input.kind, "hook"),
+      title: text(input.title, "Agent activity recorded"),
+      detail: text(input.detail, "A code agent changed the workspace."),
+      filesChanged: Array.isArray(input.filesChanged)
+        ? input.filesChanged.filter((file) => typeof file === "string").join(", ")
+        : text(input.filesChanged, ""),
+      status: text(input.status, "info"),
+      createdAt: now,
+    });
+
+    const update: Record<string, unknown> = {
+      status: signal.status === "error" ? "needs-attention" : "observing",
+      updatedAt: now,
+    };
+    for (const [key, value] of Object.entries({
+      previewStatus: optionalText(input.previewStatus),
+      previewStatusReason: optionalText(input.previewStatusReason),
+      generatedState: optionalText(input.generatedState),
+      generatedChangedFiles: optionalCount(input.generatedChangedFiles),
+      authoredFiles: optionalCount(input.authoredFiles),
+      generatedFiles: optionalCount(input.generatedFiles),
+      authoredDiffCommand: optionalText(input.authoredDiffCommand),
+      generatedDiffCommand: optionalText(input.generatedDiffCommand),
+      terminalCommand: optionalText(input.terminalCommand),
+      terminalCwd: optionalText(input.terminalCwd),
+    })) {
+      if (value !== undefined) {
+        update[key] = value;
+      }
+    }
+
+    await ctx.db.agentSessions.update(session.id, update);
+    await ctx.emit("agent.signal.recorded", {
+      sessionId: session.id,
+      signalId: signal.id,
+      kind: signal.kind,
+      status: signal.status,
+    });
+
+    return signal;
+  },
+});

package/templates/agent-workroom/src/commands/recordCheckRun.ts

@@ -0,0 +1,52 @@
+import { can, command } from "forge/server";
+
+function text(value: unknown, fallback: string): string {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function duration(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+export const recordCheckRun = command({
+  auth: can("workroom.write"),
+  handler: async (ctx, args) => {
+    const input = args as {
+      sessionId?: unknown;
+      command?: unknown;
+      status?: unknown;
+      output?: unknown;
+      durationMs?: unknown;
+    };
+    const sessionId = text(input.sessionId, "");
+    if (!sessionId) {
+      throw new Error("sessionId is required");
+    }
+    const session = await ctx.db.agentSessions.get(sessionId);
+    if (!session) {
+      throw new Error("session not found");
+    }
+
+    const now = new Date().toISOString();
+    const run = await ctx.db.checkRuns.insert({
+      sessionId,
+      command: text(input.command, "forge check"),
+      status: text(input.status, "passed"),
+      output: text(input.output, ""),
+      durationMs: duration(input.durationMs),
+      createdAt: now,
+    });
+
+    await ctx.db.agentSessions.update(sessionId, {
+      status: run.status === "failed" ? "needs-attention" : "verified",
+      updatedAt: now,
+    });
+    await ctx.emit("check.run.recorded", {
+      sessionId,
+      runId: run.id,
+      status: run.status,
+    });
+
+    return run;
+  },
+});

package/templates/agent-workroom/src/forge/schema.ts

@@ -0,0 +1,54 @@
+import { defineTable } from "forge/server";
+
+export const agentSessions = defineTable({
+  name: "agentSessions",
+  fields: {
+    id: "uuid",
+    appName: "text",
+    appPath: "text",
+    previewUrl: "text",
+    previewStatus: "text",
+    previewStatusReason: "text",
+    agent: "text",
+    status: "text",
+    objective: "text",
+    generatedState: "text",
+    generatedChangedFiles: "number",
+    authoredFiles: "number",
+    generatedFiles: "number",
+    authoredDiffCommand: "text",
+    generatedDiffCommand: "text",
+    terminalCommand: "text",
+    terminalCwd: "text",
+    createdAt: "timestamp",
+    updatedAt: "timestamp",
+  },
+});
+
+export const agentSignals = defineTable({
+  name: "agentSignals",
+  fields: {
+    id: "uuid",
+    sessionId: "uuid",
+    source: "text",
+    kind: "text",
+    title: "text",
+    detail: "text",
+    filesChanged: "text",
+    status: "text",
+    createdAt: "timestamp",
+  },
+});
+
+export const checkRuns = defineTable({
+  name: "checkRuns",
+  fields: {
+    id: "uuid",
+    sessionId: "uuid",
+    command: "text",
+    status: "text",
+    output: "text",
+    durationMs: "number",
+    createdAt: "timestamp",
+  },
+});

package/templates/agent-workroom/src/policies.ts

@@ -0,0 +1,6 @@
+import { canRole, definePolicies } from "forge/policy";
+
+export const policies = definePolicies({
+  "workroom.read": canRole("owner", "admin", "member"),
+  "workroom.write": canRole("owner", "admin", "member"),
+});

package/templates/agent-workroom/src/queries/listWorkrooms.ts

@@ -0,0 +1,11 @@
+import { can, query } from "forge/server";
+
+export const listWorkrooms = query({
+  auth: can("workroom.read"),
+  handler: async (ctx) => {
+    const sessions = await ctx.db.agentSessions.all();
+    return sessions
+      .slice()
+      .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  },
+});

package/templates/agent-workroom/src/queries/liveWorkroom.ts

@@ -0,0 +1,63 @@
+import { can, liveQuery } from "forge/server";
+
+type RowWithTime = {
+  createdAt?: string;
+  updatedAt?: string;
+};
+
+function newestFirst<T extends RowWithTime>(rows: T[]): T[] {
+  return rows.slice().sort((a, b) => {
+    const bTime = String(b.updatedAt ?? b.createdAt ?? "");
+    const aTime = String(a.updatedAt ?? a.createdAt ?? "");
+    return bTime.localeCompare(aTime);
+  });
+}
+
+export const liveWorkroom = liveQuery({
+  auth: can("workroom.read"),
+  handler: async (ctx, args) => {
+    const input = args as { sessionId?: unknown };
+    const sessions = newestFirst(await ctx.db.agentSessions.all());
+    const selectedSession =
+      typeof input.sessionId === "string" && input.sessionId.trim().length > 0
+        ? await ctx.db.agentSessions.get(input.sessionId)
+        : sessions[0] ?? null;
+
+    if (!selectedSession) {
+      return {
+        sessions,
+        selectedSession: null,
+        signals: [],
+        checks: [],
+        stats: {
+          signalCount: 0,
+          checkCount: 0,
+          failingChecks: 0,
+          filesTouched: 0,
+        },
+      };
+    }
+
+    const signals = newestFirst(await ctx.db.agentSignals.where({ sessionId: selectedSession.id }));
+    const checks = newestFirst(await ctx.db.checkRuns.where({ sessionId: selectedSession.id }));
+    const files = new Set(
+      signals
+        .flatMap((signal) => String(signal.filesChanged ?? "").split(","))
+        .map((file) => file.trim())
+        .filter(Boolean),
+    );
+
+    return {
+      sessions,
+      selectedSession,
+      signals,
+      checks,
+      stats: {
+        signalCount: signals.length,
+        checkCount: checks.length,
+        failingChecks: checks.filter((check) => check.status === "failed").length,
+        filesTouched: files.size,
+      },
+    };
+  },
+});

package/templates/agent-workroom/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*.ts",
+    "forge.config.ts"
+  ]
+}

package/templates/agent-workroom/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__FORGE_APP_TITLE__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/agent-workroom/web/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__FORGE_APP_NAME__-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^6.0.2",
+    "vite": "^8.0.16",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.3"
+  }
+}