@opencomputer/cli 0.3.12 → 0.4.0

package/dist/project.js

@@ -56,6 +56,14 @@ async function prepareInitializationTarget(root, template) {
         "package.json",
         "agent.ts",
         "instructions.md",
+        ...(template.id === "pr-review-readiness"
+            ? [
+                "tools/github.ts",
+                "connections/github.json",
+                "skills/review-pr/SKILL.md",
+                "evals/pr-review-cases.md",
+            ]
+            : []),
         ...(template.integrations.includes("Gmail")
             ? ["tools/gmail.ts", "connections/google.json"]
             : []),
@@ -80,7 +88,13 @@ async function prepareInitializationTarget(root, template) {
 }
 async function updateGitignore(root) {
     const path = resolve(root, ".gitignore");
-    const required = ["node_modules/", ".opencomputer/", ".env"];
+    const required = [
+        "node_modules/",
+        "dist/",
+        ".opencomputer/",
+        ".env",
+        ".env.local",
+    ];
     let existing = "";
     try {
         existing = await readFile(path, "utf8");
@@ -219,6 +233,63 @@ user's managed connection and cannot authenticate as that user.
 
 ## Example requests
 
+${template.suggestedPrompts.map((prompt) => `- ${prompt}`).join("\n")}
+`;
+    }
+    if (template.id === "pr-review-readiness") {
+        return `# ${template.name}
+
+You are a code-review readiness agent. Decide whether a connected GitHub pull
+request is ready to consume a human reviewer's attention.
+
+${template.description}
+
+## Required workflow
+
+1. Require an exact GitHub pull request URL and a connected GitHub account with
+   access to its repository.
+2. Call the \`github_pr_context\` tool. Record the current head SHA and treat
+   every conclusion as applying only to that SHA.
+3. Read every returned issue comment, submitted review, inline review comment,
+   changed-file record, and available diff hunk. Group inline replies using
+   their reply relationships.
+4. Do not call \`github_checkout\` by default. Use it only when the returned
+   diff and file patches are insufficient and surrounding repository guidance
+   is needed. It materializes a bounded exact-head working set containing the
+   changed files plus relevant instructions and manifests; it does not download
+   the entire repository or create a Git remote. Read materialized files from
+   the relative \`destination\` returned by the tool.
+5. Reconcile every substantive prior review finding against the current head.
+   A resolved conversation is evidence, not proof: verify the current code.
+6. Review the complete available change for correctness, security, regressions,
+   error handling, test coverage, and repository conventions. Run focused local
+   tests when practical, but never claim a test passed unless it completed.
+7. Return exactly one verdict:
+   - \`READY_FOR_HUMAN_REVIEW\`: no known blocking issue remains and the change
+     has adequate validation for a human to review efficiently.
+   - \`NOT_READY\`: one or more actionable blocking issues remain.
+   - \`NEEDS_INFORMATION\`: required code, diff content, repository access, or
+     validation is unavailable.
+
+## Output
+
+Lead with the verdict and head SHA. Then provide blocking findings, prior
+review-comment status, validation performed, non-blocking notes, and the
+recommended next action. Cite file paths and lines when evidence allows it.
+Return the complete report in the current OpenComputer session.
+
+## Immutable safety boundary
+
+GitHub credentials remain in the OpenComputer control plane. The runtime gets
+only a session-scoped broker token, and the broker permits only allowlisted GET
+requests even though GitHub's classic private-repository OAuth scope is broad.
+Never push, create a branch, approve, merge, request changes, dismiss a review,
+or post/edit/delete a GitHub comment. Never add a Git remote or attempt to
+discover credentials. If the connected account cannot access the PR, return
+\`NEEDS_INFORMATION\` with the exact limitation.
+
+## Example requests
+
 ${template.suggestedPrompts.map((prompt) => `- ${prompt}`).join("\n")}
 `;
     }
@@ -578,6 +649,291 @@ export const create_time_off = tool({
 });
 `;
 }
+function githubReviewToolSource() {
+    return `import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+
+const MAX_PAGES = 10;
+const MAX_CHECKOUT_FILES = 100;
+const MAX_CHECKOUT_BYTES = 20 * 1024 * 1024;
+
+function parsePullRequestUrl(value: string): {
+  repository: string;
+  number: number;
+} {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("pullRequestUrl must be a complete GitHub pull request URL");
+  }
+  const parts = url.pathname.split("/").filter(Boolean);
+  const number = Number(parts[3]);
+  if (
+    url.protocol !== "https:" ||
+    url.hostname.toLowerCase() !== "github.com" ||
+    parts.length !== 4 ||
+    parts[2] !== "pull" ||
+    !Number.isSafeInteger(number) ||
+    number < 1 ||
+    !/^[A-Za-z0-9_.-]+$/.test(parts[0] ?? "") ||
+    !/^[A-Za-z0-9_.-]+$/.test(parts[1] ?? "")
+  ) {
+    throw new Error("Expected https://github.com/<owner>/<repository>/pull/<number>");
+  }
+  return { repository: parts[0] + "/" + parts[1], number };
+}
+
+async function githubFetch(path: string, accept = "application/vnd.github+json") {
+  const base = process.env.OPENCOMPUTER_CONNECTIONS_URL;
+  const token = process.env.OPENCOMPUTER_CONNECTION_TOKEN;
+  if (!base || !token) {
+    throw new Error("OpenComputer GitHub connection is unavailable");
+  }
+  const response = await fetch(base.replace(/\\\/$/, "") + "/github/fetch", {
+    method: "POST",
+    headers: {
+      authorization: "Bearer " + token,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      service: "github",
+      method: "GET",
+      path,
+      headers: { accept, "x-github-api-version": "2022-11-28" },
+    }),
+  });
+  if (!response.ok) {
+    const failure = (await response.json().catch(() => ({}))) as {
+      error?: { message?: string };
+    };
+    throw new Error(failure.error?.message ?? "GitHub connection request failed");
+  }
+  const result = (await response.json()) as {
+    status?: number;
+    body?: string;
+  };
+  if (!result.status || result.status >= 400) {
+    throw new Error(result.body ?? "GitHub request failed");
+  }
+  return result.body ?? "";
+}
+
+async function githubJson(path: string): Promise<Record<string, unknown>> {
+  return JSON.parse(await githubFetch(path)) as Record<string, unknown>;
+}
+
+async function githubPages(path: string): Promise<{
+  items: Record<string, unknown>[];
+  truncated: boolean;
+}> {
+  const items: Record<string, unknown>[] = [];
+  let lastPageWasFull = false;
+  for (let page = 1; page <= MAX_PAGES; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const batch = JSON.parse(
+      await githubFetch(path + separator + "per_page=100&page=" + String(page)),
+    ) as Record<string, unknown>[];
+    items.push(...batch);
+    lastPageWasFull = batch.length === 100;
+    if (!lastPageWasFull) break;
+  }
+  return { items, truncated: lastPageWasFull };
+}
+
+export const pr_context = tool({
+  description:
+    "Read-only: fetch an accessible GitHub PR, all available issue comments, reviews, inline review comments, changed files, and the full available diff through the connection broker.",
+  args: {
+    pullRequestUrl: tool.schema.string(),
+  },
+  async execute(args) {
+    const { repository, number } = parsePullRequestUrl(args.pullRequestUrl);
+    const prefix = "/repos/" + repository;
+    const [pull, comments, reviews, reviewComments, files] = await Promise.all([
+      githubJson(prefix + "/pulls/" + String(number)),
+      githubPages(prefix + "/issues/" + String(number) + "/comments"),
+      githubPages(prefix + "/pulls/" + String(number) + "/reviews"),
+      githubPages(prefix + "/pulls/" + String(number) + "/comments"),
+      githubPages(prefix + "/pulls/" + String(number) + "/files"),
+    ]);
+    let diff: string | undefined;
+    try {
+      diff = await githubFetch(
+        prefix + "/pulls/" + String(number),
+        "application/vnd.github.v3.diff",
+      );
+    } catch {
+      // Per-file patches remain available. The completeness marker below tells
+      // the reviewer that it must not claim full-diff coverage.
+    }
+    const head =
+      pull.head && typeof pull.head === "object"
+        ? (pull.head as Record<string, unknown>)
+        : {};
+    const base =
+      pull.base && typeof pull.base === "object"
+        ? (pull.base as Record<string, unknown>)
+        : {};
+    const maximumDiff = 2_000_000;
+    return JSON.stringify({
+      repository,
+      number,
+      url: args.pullRequestUrl,
+      pull: {
+        title: pull.title,
+        body: pull.body,
+        state: pull.state,
+        draft: pull.draft,
+        mergeable: pull.mergeable,
+        mergeableState: pull.mergeable_state,
+        author: pull.user,
+        additions: pull.additions,
+        deletions: pull.deletions,
+        changedFiles: pull.changed_files,
+        head: { ref: head.ref, sha: head.sha },
+        base: { ref: base.ref, sha: base.sha },
+      },
+      comments: comments.items,
+      reviews: reviews.items,
+      reviewComments: reviewComments.items,
+      files: files.items,
+      diff: diff?.slice(0, maximumDiff),
+      completeness: {
+        comments: !comments.truncated,
+        reviews: !reviews.truncated,
+        reviewComments: !reviewComments.truncated,
+        files: !files.truncated,
+        diff: Boolean(diff) && (diff?.length ?? 0) <= maximumDiff,
+      },
+    });
+  },
+});
+
+export const checkout = tool({
+  description:
+    "Read-only: materialize changed files plus relevant repository instructions and manifests from the exact PR head into a bounded session-workspace directory, without downloading the whole repository or creating a Git remote. Use the destination returned by this tool for subsequent file reads.",
+  args: {
+    pullRequestUrl: tool.schema.string(),
+  },
+  async execute(args, context) {
+    const { repository, number } = parsePullRequestUrl(args.pullRequestUrl);
+    const pull = await githubJson(
+      "/repos/" + repository + "/pulls/" + String(number),
+    );
+    const head =
+      pull.head && typeof pull.head === "object"
+        ? (pull.head as Record<string, unknown>)
+        : {};
+    if (typeof head.sha !== "string" || !/^[a-f0-9]{40}$/i.test(head.sha)) {
+      throw new Error("GitHub did not return a valid PR head SHA");
+    }
+    const workspace = resolve(context.directory);
+    const destinationName =
+      "github-pr-" + number + "-" + head.sha.slice(0, 12).toLowerCase();
+    const destination = resolve(workspace, destinationName);
+    if (!destination.startsWith(workspace + sep)) {
+      throw new Error("generated checkout destination escaped the workspace");
+    }
+    const changed = await githubPages(
+      "/repos/" + repository + "/pulls/" + String(number) + "/files",
+    );
+    const changedPaths = new Set(
+      changed.items
+        .map((file) => file.filename)
+        .filter((path): path is string => typeof path === "string"),
+    );
+    const candidates = new Set(changedPaths);
+    const guidanceNames = [
+      "AGENTS.md",
+      "README.md",
+      "CONTRIBUTING.md",
+      "package.json",
+      "pnpm-workspace.yaml",
+      "go.mod",
+      "go.work",
+      "Cargo.toml",
+      "pyproject.toml",
+      "requirements.txt",
+    ];
+    for (const name of guidanceNames) candidates.add(name);
+    for (const path of changedPaths) {
+      const parts = path.split("/");
+      for (let depth = 1; depth < parts.length; depth += 1) {
+        const directory = parts.slice(0, depth).join("/");
+        for (const name of ["AGENTS.md", "README.md", "package.json"]) {
+          candidates.add(directory + "/" + name);
+        }
+      }
+    }
+    const requested = [...candidates].slice(0, MAX_CHECKOUT_FILES);
+    await mkdir(destination, { recursive: true });
+    const materialized: string[] = [];
+    const missingChanged: string[] = [];
+    let totalBytes = 0;
+    let limitExceeded = false;
+    for (let offset = 0; offset < requested.length; offset += 8) {
+      const batch = requested.slice(offset, offset + 8);
+      await Promise.all(
+        batch.map(async (path) => {
+          const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+          try {
+            const file = await githubJson(
+              "/repos/" + repository + "/contents/" + encodedPath + "?ref=" + head.sha,
+            );
+            let content: Buffer;
+            if (file.encoding === "base64" && typeof file.content === "string") {
+              content = Buffer.from(file.content.replace(/\\s+/g, ""), "base64");
+            } else if (typeof file.sha === "string" && /^[a-f0-9]{40}$/i.test(file.sha)) {
+              const blob = await githubJson(
+                "/repos/" + repository + "/git/blobs/" + file.sha,
+              );
+              if (blob.encoding !== "base64" || typeof blob.content !== "string") {
+                throw new Error("unsupported GitHub content encoding");
+              }
+              content = Buffer.from(blob.content.replace(/\\s+/g, ""), "base64");
+            } else {
+              throw new Error("GitHub did not return file content");
+            }
+            totalBytes += content.byteLength;
+            if (totalBytes > MAX_CHECKOUT_BYTES) {
+              limitExceeded = true;
+              throw new Error("bounded checkout exceeds 20 MiB");
+            }
+            const output = resolve(destination, path);
+            if (!output.startsWith(destination + sep)) {
+              throw new Error("GitHub returned an unsafe repository path");
+            }
+            await mkdir(resolve(output, ".."), { recursive: true });
+            await writeFile(output, content);
+            materialized.push(path);
+          } catch (error) {
+            if (changedPaths.has(path)) missingChanged.push(path);
+          }
+        }),
+      );
+    }
+    return JSON.stringify({
+      repository,
+      pullRequestNumber: number,
+      headSha: head.sha,
+      destination: destinationName,
+      materialized: materialized.sort(),
+      bytes: totalBytes,
+      missingChanged: missingChanged.sort(),
+      complete:
+        !changed.truncated &&
+        candidates.size <= MAX_CHECKOUT_FILES &&
+        !limitExceeded &&
+        missingChanged.length === 0,
+      scope: "changed files plus relevant instructions and manifests",
+      remoteConfigured: false,
+    });
+  },
+});
+`;
+}
 function connectionControlToolSource() {
     return `import { tool } from "@opencode-ai/plugin";
 
@@ -651,7 +1007,7 @@ export const request = tool({
   description:
     "Ask the current user to connect an account. Use gmail for an email account. Set newAccount=true when the user asks for another account of the same service. In a messaging channel OpenComputer privately sends the authorization link to that user; otherwise the result includes the link.",
   args: {
-    service: tool.schema.enum(["gmail", "calendar", "drive", "sheets"]),
+    service: tool.schema.enum(["gmail", "calendar", "drive", "sheets", "github"]),
     label: tool.schema.string().optional(),
     newAccount: tool.schema.boolean().optional(),
   },
@@ -707,10 +1063,39 @@ export async function readManifest(root) {
 export async function findAgentRoot(startDirectory = process.cwd()) {
     let directory = resolve(startDirectory);
     for (;;) {
+        const nested = resolve(directory, "opencomputer");
         if ((await exists(resolve(directory, "opencomputer.toml"))) &&
             (await exists(resolve(directory, "instructions.md")))) {
             return directory;
         }
+        if ((await exists(resolve(nested, "opencomputer.toml"))) &&
+            (await exists(resolve(nested, "instructions.md")))) {
+            return nested;
+        }
+        for (const agentsDirectory of [
+            resolve(directory, "opencomputer", "agents"),
+            resolve(directory, "agents"),
+        ]) {
+            if (!(await exists(agentsDirectory)))
+                continue;
+            const detected = [];
+            for (const entry of await readdir(agentsDirectory, {
+                withFileTypes: true,
+            })) {
+                if (!entry.isDirectory())
+                    continue;
+                const agent = resolve(agentsDirectory, entry.name);
+                if ((await exists(resolve(agent, "opencomputer.toml"))) &&
+                    (await exists(resolve(agent, "instructions.md")))) {
+                    detected.push(agent);
+                }
+            }
+            if (detected.length === 1)
+                return detected[0];
+            if (detected.length > 1) {
+                throw new Error("This project has multiple agents. Select an agent when starting dev mode.");
+            }
+        }
         const parent = dirname(directory);
         if (parent === directory)
             return undefined;
@@ -765,6 +1150,13 @@ export async function addCalendarTools(root) {
     ]);
     return ["tools/calendar.ts", "connections/google.json"];
 }
+export async function addGithubReviewTools(root) {
+    await mkdir(resolve(root, "tools"), { recursive: true });
+    await mkdir(resolve(root, "connections"), { recursive: true });
+    await writeFile(resolve(root, "tools", "github.ts"), githubReviewToolSource());
+    await writeFile(resolve(root, "connections", "github.json"), `${JSON.stringify({ provider: "github", services: ["github"], scopes: ["repo"] }, null, 2)}\n`);
+    return ["tools/github.ts", "connections/github.json"];
+}
 export async function addSlackChannel(root) {
     await mkdir(resolve(root, "channels"), { recursive: true });
     await mkdir(resolve(root, "slack"), { recursive: true });
@@ -804,7 +1196,7 @@ export async function addSlackChannel(root) {
     }, null, 2)}\n`);
     return ["channels/slack.ts", "slack/manifest.json"];
 }
-export async function initializeAgentProject(template, directory) {
+export async function initializeTemplateAgentProject(template, directory) {
     const root = resolve(directory);
     await prepareInitializationTarget(root, template);
     for (const path of [
@@ -893,6 +1285,66 @@ export async function initializeAgentProject(template, directory) {
     if (template.integrations.includes("Google Calendar")) {
         files.push(...(await addCalendarTools(root)));
     }
+    if (template.id === "pr-review-readiness") {
+        files.push(...(await addGithubReviewTools(root)));
+        await mkdir(resolve(root, "skills", "review-pr"), { recursive: true });
+        await writeFile(resolve(root, "skills", "review-pr", "SKILL.md"), `---
+name: review-pr
+description: Decide whether a connected GitHub pull request is ready for human review.
+---
+
+# Review PR readiness
+
+1. Call \`github_pr_context\` with the exact PR URL.
+2. Record the returned head SHA and completeness markers.
+3. Read all prior review feedback and map it to the current code.
+4. Call \`github_checkout\` only when the diff is insufficient and surrounding
+   repository instructions are required. It creates a bounded exact-head
+   working set and no Git remote. Read files from its returned relative
+   \`destination\`.
+5. Verify every prior finding against the current head.
+6. Return \`NEEDS_INFORMATION\` if any context required for a sound conclusion
+   is unavailable or marked incomplete.
+7. Otherwise return \`READY_FOR_HUMAN_REVIEW\` or \`NOT_READY\` using the rubric
+   in the agent instructions.
+
+Never use GitHub write APIs, add a Git remote, or search for credentials.
+`);
+        await writeFile(resolve(root, "evals", "pr-review-cases.md"), `# PR review readiness acceptance cases
+
+## Addressed prior feedback
+
+Prompt: Review a PR whose latest head fixes every earlier blocker.
+
+Pass criteria:
+
+- Reads PR metadata, all comment sources, changed files, and the available diff.
+- Records the exact head SHA and checks response completeness.
+- Verifies fixes in current code rather than trusting resolved-thread state.
+- Returns READY_FOR_HUMAN_REVIEW only when no blocker remains.
+- Performs no GitHub write and creates no Git remote.
+
+## Remaining blocker
+
+Prompt: Review a PR with an unresolved correctness regression.
+
+Pass criteria:
+
+- Returns NOT_READY and leads with the concrete blocker.
+- Cites the affected file and explains the failure mode.
+- Distinguishes prior-review status from newly discovered findings.
+
+## Inaccessible or incomplete PR
+
+Prompt: Review a PR that the connected account cannot access or whose response has incomplete pagination.
+
+Pass criteria:
+
+- Returns NEEDS_INFORMATION rather than guessing readiness.
+- Identifies the exact access, content, or validation limitation.
+`);
+        files.push("skills/review-pr/SKILL.md", "evals/pr-review-cases.md");
+    }
     if (template.id === "email-triage") {
         await mkdir(resolve(root, "skills", "triage-inbox"), {
             recursive: true,
@@ -1020,6 +1472,393 @@ Pass criteria:
     }
     return { root, manifest, files };
 }
+const HELLO_WORLD_TEMPLATE = {
+    id: "hello-world",
+    name: "Hello World",
+    description: "Greet the user, explain that this agent is running live, and answer simple questions clearly.",
+    category: "Getting started",
+    integrations: [],
+    suggestedPrompts: ["Say hello and tell me what you can do."],
+};
+export async function assertStarterTarget(directory) {
+    const root = resolve(directory);
+    if (!(await exists(root))) {
+        await mkdir(root, { recursive: true });
+        return;
+    }
+    const reserved = [
+        "opencomputer/project.ts",
+        "opencomputer/agents/hello-world/opencomputer.toml",
+        "package.json",
+        "vite.config.ts",
+        "index.html",
+        "src/App.tsx",
+        "src/main.tsx",
+    ];
+    const conflicts = [];
+    for (const path of reserved) {
+        if (await exists(resolve(root, path)))
+            conflicts.push(path);
+    }
+    if (conflicts.length) {
+        throw new Error(`Target already contains OpenComputer app files: ${conflicts.join(", ")}`);
+    }
+}
+export async function initializeAgentProject(directory, project) {
+    const root = resolve(directory);
+    const agentRoot = resolve(root, "opencomputer", "agents", "hello-world");
+    await assertStarterTarget(root);
+    const initialized = await initializeTemplateAgentProject(HELLO_WORLD_TEMPLATE, agentRoot);
+    const manifest = {
+        ...initialized.manifest,
+        ...(project ? { id: project.agentId } : {}),
+        name: "Hello World",
+    };
+    await writeManifest(agentRoot, manifest);
+    await rm(resolve(agentRoot, "package.json"), { force: true });
+    await rm(resolve(agentRoot, ".gitignore"), { force: true });
+    await updateGitignore(root);
+    await mkdir(resolve(root, "src"), { recursive: true });
+    await writeFile(resolve(root, "opencomputer", "project.ts"), `export default {
+  id: ${JSON.stringify(project?.id ?? manifest.id)},
+  name: ${JSON.stringify(project?.name ?? "Hello World")},
+  agents: ["hello-world"],
+};
+`);
+    await writeFile(resolve(root, "package.json"), `${JSON.stringify({
+        name: `opencomputer-app-${manifest.id}`,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: {
+            dev: "opencomputer dev",
+            "dev:web": "vite",
+            build: "tsc -b && vite build",
+            session: "opencomputer session",
+            deploy: "opencomputer deploy",
+        },
+        dependencies: {
+            react: "^19.2.0",
+            "react-dom": "^19.2.0",
+        },
+        devDependencies: {
+            "@opencomputer/cli": "^0.4.0",
+            "@opencode-ai/plugin": "^1.18.4",
+            "@types/node": "^24.0.0",
+            "@types/react": "^19.2.0",
+            "@types/react-dom": "^19.2.0",
+            "@vitejs/plugin-react": "^6.0.0",
+            "opencode-ai": "1.18.4",
+            typescript: "^5.9.0",
+            vite: "^8.0.0",
+        },
+    }, null, 2)}\n`);
+    await writeFile(resolve(root, "vite.config.ts"), `import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+function openComputerDev() {
+  try {
+    return JSON.parse(
+      readFileSync(
+        resolve("opencomputer/agents/hello-world/.opencomputer/dev.json"),
+        "utf8",
+      ),
+    ) as { url: string; token: string };
+  } catch {
+    throw new Error(
+      "OpenComputer is not running. Start npm run dev in another terminal first.",
+    );
+  }
+}
+
+export default defineConfig(({ command }) => {
+  const dev = command === "serve" ? openComputerDev() : undefined;
+  return {
+    plugins: [react()],
+    ...(dev ? { server: {
+      proxy: {
+        "/api/opencomputer": {
+          target: dev.url,
+          headers: { authorization: \`Bearer \${dev.token}\` },
+          rewrite: (path) => path.replace(/^\\/api\\/opencomputer/, ""),
+        },
+      },
+    } } : {}),
+  };
+});
+`);
+    await writeFile(resolve(root, "tsconfig.json"), `${JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            useDefineForClassFields: true,
+            lib: ["ES2022", "DOM", "DOM.Iterable"],
+            allowJs: false,
+            skipLibCheck: true,
+            esModuleInterop: true,
+            allowSyntheticDefaultImports: true,
+            strict: true,
+            forceConsistentCasingInFileNames: true,
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            resolveJsonModule: true,
+            isolatedModules: true,
+            noEmit: true,
+            jsx: "react-jsx",
+            types: ["node", "vite/client"],
+        },
+        include: ["src", "vite.config.ts"],
+    }, null, 2)}\n`);
+    await writeFile(resolve(root, "index.html"), `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#11110f" />
+    <title>Hello World · OpenComputer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`);
+    await writeFile(resolve(root, "src", "use-agent.ts"), `import { useCallback, useState } from "react";
+
+export interface AgentMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+}
+
+interface AgentEvent {
+  type: string;
+  data: Record<string, unknown>;
+}
+
+export function useAgent() {
+  const [messages, setMessages] = useState<AgentMessage[]>([]);
+  const [sessionId, setSessionId] = useState<string>();
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<string>();
+
+  const send = useCallback(async (value: string) => {
+    const prompt = value.trim();
+    if (!prompt || isRunning) return;
+    const userMessage: AgentMessage = {
+      id: crypto.randomUUID(),
+      role: "user",
+      text: prompt,
+    };
+    const assistantId = crypto.randomUUID();
+    setMessages((current) => [
+      ...current,
+      userMessage,
+      { id: assistantId, role: "assistant", text: "" },
+    ]);
+    setIsRunning(true);
+    setError(undefined);
+    try {
+      const endpoint = sessionId
+        ? \`/api/opencomputer/sessions/\${encodeURIComponent(sessionId)}\`
+        : "/api/opencomputer/sessions";
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ prompt }),
+      });
+      if (!response.ok || !response.body) {
+        throw new Error(\`Agent request failed (\${response.status})\`);
+      }
+      const createdSession = response.headers.get("x-opencomputer-session-id");
+      if (createdSession) setSessionId(createdSession);
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffered = "";
+      let streamed = "";
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffered += decoder.decode(value, { stream: true });
+        const lines = buffered.split("\\n");
+        buffered = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const event = JSON.parse(line) as AgentEvent;
+          if (event.type === "message.delta") {
+            streamed += String(event.data.text ?? "");
+            setMessages((current) =>
+              current.map((message) =>
+                message.id === assistantId
+                  ? { ...message, text: streamed }
+                  : message,
+              ),
+            );
+          } else if (event.type === "message.completed" && !streamed) {
+            const text = String(event.data.text ?? "");
+            setMessages((current) =>
+              current.map((message) =>
+                message.id === assistantId ? { ...message, text } : message,
+              ),
+            );
+          } else if (event.type === "session.failed") {
+            throw new Error(String(event.data.message ?? "Agent failed"));
+          }
+        }
+      }
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      setError(message);
+      setMessages((current) =>
+        current.map((item) =>
+          item.id === assistantId && !item.text
+            ? { ...item, text: "I couldn't complete that request." }
+            : item,
+        ),
+      );
+    } finally {
+      setIsRunning(false);
+    }
+  }, [isRunning, sessionId]);
+
+  return { messages, send, isRunning, error };
+}
+`);
+    await writeFile(resolve(root, "src", "App.tsx"), `import { FormEvent, useState } from "react";
+import { useAgent } from "./use-agent";
+
+export default function App() {
+  const [input, setInput] = useState("");
+  const { messages, send, isRunning, error } = useAgent();
+
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    const prompt = input;
+    setInput("");
+    void send(prompt);
+  }
+
+  return (
+    <main>
+      <section className="hero">
+        <span className="eyebrow">OpenComputer</span>
+        <h1>Hello, world.</h1>
+        <p>Your first agent is live. Ask it anything to see the local backend and React app working together.</p>
+      </section>
+
+      <section className="chat" aria-label="Agent conversation">
+        <div className="messages">
+          {messages.length === 0 ? (
+            <button className="suggestion" onClick={() => void send("Say hello and tell me what you can do.")}>
+              Say hello and tell me what you can do →
+            </button>
+          ) : (
+            messages.map((message) => (
+              <article key={message.id} className={message.role}>
+                <strong>{message.role === "user" ? "You" : "Agent"}</strong>
+                <p>{message.text || "Thinking…"}</p>
+              </article>
+            ))
+          )}
+        </div>
+        {error ? <p className="error">{error}</p> : null}
+        <form onSubmit={submit}>
+          <input
+            value={input}
+            onChange={(event) => setInput(event.target.value)}
+            placeholder="Message the hello-world agent…"
+            aria-label="Message"
+          />
+          <button disabled={isRunning || !input.trim()}>
+            {isRunning ? "Running…" : "Send"}
+          </button>
+        </form>
+      </section>
+    </main>
+  );
+}
+`);
+    await writeFile(resolve(root, "src", "main.tsx"), `import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+`);
+    await writeFile(resolve(root, "src", "styles.css"), `@import url("https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600&family=DM+Serif+Display&display=swap");
+
+:root { color: #1d1c19; background: #f4f1e9; font-family: "DM Sans", sans-serif; }
+* { box-sizing: border-box; }
+body { margin: 0; min-width: 320px; min-height: 100vh; }
+button, input { font: inherit; }
+main { width: min(760px, calc(100% - 32px)); margin: 0 auto; padding: 12vh 0 48px; }
+.hero { margin-bottom: 36px; }
+.eyebrow { color: #706b60; font-size: 12px; font-weight: 600; letter-spacing: .12em; text-transform: uppercase; }
+h1 { margin: 10px 0; font: 400 clamp(48px, 10vw, 84px)/.95 "DM Serif Display", serif; }
+.hero p { max-width: 580px; color: #625e55; font-size: 18px; line-height: 1.6; }
+.chat { overflow: hidden; border: 1px solid #d9d4c8; border-radius: 18px; background: rgba(255,255,255,.72); box-shadow: 0 18px 60px rgba(56,48,34,.08); }
+.messages { display: grid; gap: 14px; min-height: 260px; max-height: 52vh; overflow-y: auto; padding: 24px; }
+article { max-width: 82%; border-radius: 14px; padding: 12px 14px; }
+article strong { display: block; margin-bottom: 4px; font-size: 12px; color: #777166; }
+article p { margin: 0; line-height: 1.55; white-space: pre-wrap; }
+article.user { justify-self: end; background: #1d1c19; color: white; }
+article.user strong { color: #bdb7ab; }
+article.assistant { background: #ece8de; }
+.suggestion { align-self: center; justify-self: center; border: 1px solid #d9d4c8; border-radius: 999px; background: transparent; padding: 10px 16px; cursor: pointer; }
+.suggestion:hover { background: #ece8de; }
+.error { margin: 0 24px 12px; color: #a33a2b; font-size: 14px; }
+form { display: flex; gap: 10px; border-top: 1px solid #ddd8cc; padding: 14px; background: white; }
+input { min-width: 0; flex: 1; border: 0; outline: 0; padding: 10px; background: transparent; }
+form button { border: 0; border-radius: 10px; background: #d85b35; color: white; padding: 10px 18px; font-weight: 600; cursor: pointer; }
+form button:disabled { cursor: default; opacity: .45; }
+`);
+    await writeFile(resolve(root, "README.md"), `# Hello World OpenComputer app
+
+This project keeps agent definitions in \`opencomputer/\` and the React app in
+\`src/\`.
+
+Start the agent server in one terminal:
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+Then start the React app in another:
+
+\`\`\`bash
+npm run dev:web
+\`\`\`
+`);
+    const appFiles = [
+        "package.json",
+        "vite.config.ts",
+        "tsconfig.json",
+        "index.html",
+        "README.md",
+        ".gitignore",
+        "src/App.tsx",
+        "src/main.tsx",
+        "src/styles.css",
+        "src/use-agent.ts",
+    ];
+    return {
+        root,
+        agentRoot,
+        manifest,
+        files: [
+            "opencomputer/project.ts",
+            ...initialized.files
+                .filter((path) => path !== "package.json" && path !== ".gitignore")
+                .map((path) => `opencomputer/agents/hello-world/${path}`),
+            ...appFiles,
+        ],
+    };
+}
 export async function prepareAgent(root) {
     const runtime = resolve(root, ".opencomputer", "runtime");
     await rm(runtime, { recursive: true, force: true });
@@ -1123,6 +1962,19 @@ async function collectFiles(root, directory = root) {
     return result;
 }
 async function validateTemplateRequirements(root, manifest) {
+    if (manifest.template === "pr-review-readiness") {
+        for (const path of [
+            "tools/github.ts",
+            "connections/github.json",
+            "skills/review-pr/SKILL.md",
+            "evals/pr-review-cases.md",
+        ]) {
+            if (!(await exists(resolve(root, path)))) {
+                throw new Error(`PR review readiness file is missing: ${path}`);
+            }
+        }
+        return;
+    }
     if (manifest.template !== "pto-calendar")
         return;
     let calendarDeclared = false;
@@ -1135,7 +1987,8 @@ async function validateTemplateRequirements(root, manifest) {
     catch {
         // Report one actionable error below for an incomplete PTO project.
     }
-    if (!(await exists(resolve(root, "tools", "calendar.ts"))) || !calendarDeclared) {
+    if (!(await exists(resolve(root, "tools", "calendar.ts"))) ||
+        !calendarDeclared) {
         throw new Error("PTO calendar tools are missing. Run `opencomputer tools add calendar` before deploying.");
     }
 }