forgeos 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/forge/make/index.ts

@@ -10,6 +10,9 @@ import { parseFieldSpec, parseFields, splitTopLevel } from "./fields.ts";
 import { camelCase, kebabCase, pascalCase, singularize, titleCase } from "./naming.ts";
 import {
   renderAction,
+  renderAiAgentFile,
+  renderAiChatComponent,
+  renderAiChatPage,
   renderCreateCommand,
   renderCreateForm,
   renderDeleteCommand,
@@ -17,6 +20,7 @@ import {
   renderListComponent,
   renderListQuery,
   renderLiveQuery,
+  renderNextAiPackage,
   renderPage,
   renderPlaceholderTest,
   renderPolicyFile,
@@ -57,6 +61,7 @@ export const MAKE_PRIMITIVES: MakePrimitive[] = [
   "component",
   "page",
   "ui",
+  "ai-chat",
   "resource",
   "apply",
   "rollback",
@@ -103,6 +108,8 @@ const EXPLANATIONS: Record<MakeIntent["kind"], string> = {
     "Adds a minimal app page under web/app/<route>/page.tsx.",
   ui:
     "Adds a minimal Vite React web app with ForgeProvider devAuth and a generated client bridge.",
+  "ai-chat":
+    "Adds a Forge AI agent definition and a React chat component that calls the Forge /ai/agents/run runtime endpoint.",
   resource:
     "Creates a full resource slice: table, policies, CRUD commands, queries, liveQuery, action, optional React, and tests.",
 };
@@ -521,7 +528,7 @@ function buildIntent(options: MakeCommandOptions): {
     );
   }
   const name = options.name ?? (kind === "field" ? "" : undefined);
-  if (!name && !["component", "page", "ui"].includes(kind)) {
+  if (!name && !["component", "page", "ui", "ai-chat"].includes(kind)) {
     diagnostics.push(
       diagnostic("error", "FORGE_MAKE_PATCH_UNSAFE", `forge make ${kind} requires a name`),
     );
@@ -555,7 +562,8 @@ function buildIntent(options: MakeCommandOptions): {
         kind === "resource" ||
         kind === "component" ||
         kind === "page" ||
-        kind === "ui",
+        kind === "ui" ||
+        kind === "ai-chat",
       tests: options.withTests || kind === "resource",
       policy:
         options.policy ??
@@ -566,7 +574,7 @@ function buildIntent(options: MakeCommandOptions): {
       trigger: options.trigger ?? options.event ?? (table ? `${singular}.created` : undefined),
       component: options.component,
       route: options.name ? kebabCase(options.name) : undefined,
-      withAi: options.withAi,
+      withAi: options.withAi || kind === "ai-chat",
       withCreateForm: options.withCreateForm || kind === "resource",
     },
   };
@@ -600,6 +608,77 @@ function addPolicies(plan: MakePlan, workspaceRoot: string, entries: Record<stri
   plan.diagnostics.push(...next.diagnostics);
 }
 
+function addWebAiDependencies(plan: MakePlan, workspaceRoot: string, appName: string): void {
+  const desired: Record<string, string> = {
+    "@ai-sdk/react": "^3.0.0",
+    ai: "^6.0.0",
+  };
+  const plannedPackage = plan.filesToCreate.find((file) => file.file === "web/package.json");
+  if (plannedPackage) {
+    try {
+      const parsed = JSON.parse(plannedPackage.content) as { dependencies?: Record<string, string> };
+      parsed.dependencies = { ...(parsed.dependencies ?? {}), ...desired };
+      plannedPackage.content = `${JSON.stringify(parsed, null, 2)}\n`;
+      return;
+    } catch {
+      plan.diagnostics.push(
+        diagnostic(
+          "warning",
+          "FORGE_MAKE_PACKAGE_JSON_UNSUPPORTED_SHAPE",
+          "could not update planned web/package.json with AI SDK dependencies",
+          "web/package.json",
+        ),
+      );
+      return;
+    }
+  }
+
+  const existing = readIfExists(workspaceRoot, "web/package.json");
+  if (!existing) {
+    plan.filesToCreate.push(
+      createFile(
+        workspaceRoot,
+        "web/package.json",
+        "Add web package with AI SDK dependencies",
+        renderNextAiPackage(appName),
+      ),
+    );
+    return;
+  }
+
+  try {
+    const parsed = JSON.parse(existing) as { dependencies?: Record<string, string> };
+    const dependencies = { ...(parsed.dependencies ?? {}) };
+    let changed = false;
+    for (const [name, version] of Object.entries(desired)) {
+      if (dependencies[name] !== version) {
+        dependencies[name] = version;
+        changed = true;
+      }
+    }
+    if (!changed) {
+      return;
+    }
+    parsed.dependencies = dependencies;
+    plan.filesToModify.push({
+      file: "web/package.json",
+      kind: "replace-section",
+      description: "Add AI SDK dependencies to web package",
+      beforeHash: hashStable(existing),
+      afterPreview: `${JSON.stringify(parsed, null, 2)}\n`,
+    });
+  } catch {
+    plan.diagnostics.push(
+      diagnostic(
+        "warning",
+        "FORGE_MAKE_PACKAGE_JSON_UNSUPPORTED_SHAPE",
+        "could not update web/package.json with AI SDK dependencies",
+        "web/package.json",
+      ),
+    );
+  }
+}
+
 function addRuntimeFiles(plan: MakePlan, workspaceRoot: string, intent: MakeIntent): void {
   const table = intent.table ?? intent.name;
   const singular = singularize(table);
@@ -670,6 +749,50 @@ function addFrontendFiles(plan: MakePlan, workspaceRoot: string, intent: MakeInt
   const table = intent.table ?? intent.name;
   const singular = singularize(table);
   const pascal = pascalCase(singular);
+  if (intent.kind === "ai-chat") {
+    const name = intent.name || "support";
+    const hasViteSource = fileExists(workspaceRoot, "web/src") || fileExists(workspaceRoot, "web/src/main.tsx");
+    const bridgeFile = hasViteSource ? "web/src/lib/forge.ts" : "web/lib/forge.ts";
+    const componentFile = hasViteSource
+      ? `web/src/components/${pascalCase(name)}AiChat.tsx`
+      : `web/components/${pascalCase(name)}AiChat.tsx`;
+    addWebAiDependencies(plan, workspaceRoot, name);
+    if (!fileExists(workspaceRoot, bridgeFile)) {
+      plan.filesToCreate.push(
+        createFile(
+          workspaceRoot,
+          bridgeFile,
+          "Add Forge client bridge",
+          hasViteSource ? renderWebBridge() : renderWebRootBridge(),
+        ),
+      );
+    }
+    plan.filesToCreate.push(
+      createFile(
+        workspaceRoot,
+        `src/ai/${camelCase(name)}Agent.ts`,
+        `Add AI agent '${name}'`,
+        renderAiAgentFile(name),
+      ),
+      createFile(
+        workspaceRoot,
+        componentFile,
+        `Add AI chat component '${name}'`,
+        renderAiChatComponent(name),
+      ),
+    );
+    if (fileExists(workspaceRoot, "web/app") || fileExists(workspaceRoot, "web/app/layout.tsx")) {
+      plan.filesToCreate.push(
+        createFile(
+          workspaceRoot,
+          `web/app/${kebabCase(name)}-ai/page.tsx`,
+          `Add AI chat page '${name}'`,
+          renderAiChatPage(name),
+        ),
+      );
+    }
+    return;
+  }
   if (intent.kind === "ui") {
     plan.filesToCreate.push(
       createFile(workspaceRoot, "web/package.json", "Add Vite React web package", renderVitePackage(intent.name)),

package/src/forge/make/templates.ts

@@ -351,6 +351,166 @@ export default function ${pascal}Page() {
 `;
 }
 
+export function renderAiAgentFile(name: string): string {
+  const camel = camelCase(name);
+  const pascal = pascalCase(name);
+  return `import { agent, aiTool } from "forge/server";
+import { z } from "zod";
+
+export const ${camel}ProjectContext = aiTool({
+  description: "Return concise project context for the ${pascal} agent.",
+  inputSchema: z.object({
+    topic: z.string().optional(),
+  }),
+  outputSchema: z.object({
+    context: z.string(),
+  }),
+  risk: "read",
+  strict: true,
+  needsApproval: false,
+  handler: async (_ctx, input) => ({
+    context: \`ForgeOS project context for \${input.topic ?? "the current request"}.\`,
+  }),
+});
+
+export const ${camel}Agent = agent({
+  provider: "gateway",
+  model: "openai/gpt-5.4",
+  instructions: "You are a ForgeOS app agent. Use Forge tools before answering when runtime data is needed.",
+  tools: { ${camel}ProjectContext },
+  stopWhen: { kind: "stepCount", maxSteps: 8 },
+});
+`;
+}
+
+export function renderAiChatComponent(name: string): string {
+  const pascal = pascalCase(name);
+  return `"use client";
+
+import { DefaultChatTransport } from "ai";
+import { useChat } from "@ai-sdk/react";
+import { FormEvent, useMemo, useState } from "react";
+import { forgeUrl } from "../lib/forge";
+
+export function ${pascal}AiChat() {
+  const [input, setInput] = useState("");
+  const transport = useMemo(
+    () =>
+      new DefaultChatTransport({
+        api: \`\${forgeUrl}/ai/agents/chat\`,
+        headers: {
+          "x-forge-user-id": "dev-user",
+          "x-forge-tenant-id": "dev-tenant",
+          "x-forge-role": "owner",
+        },
+        body: {
+          agent: "${camelCase(name)}Agent",
+          provider: "gateway",
+          model: "openai/gpt-5.4",
+          instructions: "Answer as a ForgeOS app agent. Use available Forge tools when useful.",
+          maxSteps: 8,
+        },
+      }),
+    [],
+  );
+  const { messages, sendMessage, status, error, addToolApprovalResponse } = useChat({
+    transport,
+  });
+  const busy = status === "submitted" || status === "streaming";
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const prompt = input.trim();
+    if (!prompt || busy) return;
+    setInput("");
+    sendMessage({ text: prompt });
+  }
+
+  return (
+    <section>
+      <div>
+        {messages.map((message) => (
+          <article key={message.id}>
+            <strong>{message.role}</strong>
+            {message.parts.map((part, index) => {
+              if (part.type === "text") {
+                return <p key={index}>{part.text}</p>;
+              }
+              if (part.type.startsWith("tool-")) {
+                const toolPart = part as typeof part & {
+                  input?: unknown;
+                  output?: unknown;
+                  approval?: { id: string; state: string };
+                };
+                return (
+                  <div key={index}>
+                    <code>{part.type.replace(/^tool-/, "")}</code>
+                    {toolPart.approval?.state === "approval-requested" ? (
+                      <span>
+                        <button
+                          type="button"
+                          onClick={() =>
+                            addToolApprovalResponse({
+                              id: toolPart.approval!.id,
+                              approved: true,
+                            })
+                          }
+                        >
+                          Approve
+                        </button>
+                        <button
+                          type="button"
+                          onClick={() =>
+                            addToolApprovalResponse({
+                              id: toolPart.approval!.id,
+                              approved: false,
+                            })
+                          }
+                        >
+                          Deny
+                        </button>
+                      </span>
+                    ) : null}
+                  </div>
+                );
+              }
+              return null;
+            })}
+          </article>
+        ))}
+      </div>
+      <form onSubmit={submit}>
+        <input
+          value={input}
+          onChange={(event) => setInput(event.currentTarget.value)}
+          placeholder="Ask the Forge agent"
+        />
+        <button type="submit" disabled={busy}>{busy ? "Running" : "Send"}</button>
+      </form>
+      {error ? <p>{error.message}</p> : null}
+    </section>
+  );
+}
+`;
+}
+
+export function renderAiChatPage(name: string): string {
+  const pascal = pascalCase(name);
+  return `"use client";
+
+import { ${pascal}AiChat } from "../../components/${pascal}AiChat";
+
+export default function ${pascal}AiPage() {
+  return (
+    <main>
+      <h1>${titleCase(name)} AI</h1>
+      <${pascal}AiChat />
+    </main>
+  );
+}
+`;
+}
+
 export function renderWebBridge(): string {
   return `export const forgeUrl =
   import.meta.env.VITE_FORGE_URL ?? "http://127.0.0.1:3765";
@@ -476,7 +636,9 @@ export function renderVitePackage(appName: string): string {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@ai-sdk/react": "^3.0.0",
     "@vitejs/plugin-react": "^4.3.4",
+    "ai": "^6.0.0",
     "vite": "^6.0.5",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
@@ -490,6 +652,32 @@ export function renderVitePackage(appName: string): string {
 `;
 }
 
+export function renderNextAiPackage(appName: string): string {
+  return `{
+  "name": "${kebabCase(appName)}-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --hostname 127.0.0.1",
+    "build": "next build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/react": "^3.0.0",
+    "ai": "^6.0.0",
+    "next": "^15.5.9",
+    "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"
+  }
+}
+`;
+}
+
 export function renderViteTsconfig(): string {
   return `{
   "compilerOptions": {

package/src/forge/make/types.ts

@@ -14,6 +14,7 @@ export type MakePrimitive =
   | "component"
   | "page"
   | "ui"
+  | "ai-chat"
   | "resource"
   | "apply"
   | "rollback";

package/src/forge/runtime/ai/context.ts

@@ -15,6 +15,8 @@ import type {
   ForgeGenerateStructuredInput,
   ForgeGenerateTextInput,
   ForgeGenerateTextResult,
+  ForgeRunAgentInput,
+  ForgeRunAgentResult,
   ForgeStreamTextInput,
   ForgeStreamTextResult,
   ForgeAiUsage,
@@ -64,6 +66,10 @@ export interface CreateAiContextOptions {
   runtimeKind: RuntimeContext;
   envelope?: AiTelemetryEnvelope;
   mockAi?: boolean;
+  toolContext?: {
+    env?: Record<string, string | undefined>;
+    auth?: unknown;
+  };
 }
 
 export function aiForbiddenInContext(runtimeKind: RuntimeContext): boolean {
@@ -94,6 +100,12 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
           `ctx.ai is forbidden in '${runtimeKind}' context`,
         );
       },
+      async runAgent() {
+        forgeError(
+          FORGE_AI_FORBIDDEN_CONTEXT,
+          `ctx.ai is forbidden in '${runtimeKind}' context`,
+        );
+      },
     };
   }
 
@@ -284,7 +296,7 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
 
       return {
         textStream: result.textStream,
-        text: result.text.then(async (text) => {
+        text: Promise.resolve(result.text).then(async (text) => {
           const usage = mapUsage(await result.usage);
           await recordAiTelemetry(telemetry, "forge.ai.stream.completed", {
             ...baseProps(),
@@ -300,7 +312,7 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
         provider: input.provider,
         model: input.model,
         purpose: input.purpose,
-        usage: result.usage.then(mapUsage),
+        usage: Promise.resolve(result.usage).then(mapUsage),
         latencyMs,
       };
     },
@@ -347,10 +359,10 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
         );
         const { generateText, Output } = await import("ai");
         const result = await generateText({
-          model: languageModel,
+          model: languageModel as never,
           prompt: input.prompt,
           system: input.system,
-          experimental_output: Output.object({ schema: input.schema as never }),
+          output: Output.object({ schema: input.schema as never }),
         });
 
         const usage = mapUsage(result.usage);
@@ -365,7 +377,7 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
           method: "generateStructured",
         });
 
-        return result.experimental_output as T;
+        return result.output as T;
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         await recordAiTelemetry(telemetry, "forge.ai.generation.failed", {
@@ -379,6 +391,198 @@ export function createAiContext(options: CreateAiContextOptions): AiContext {
         throw error;
       }
     },
+
+    async runAgent(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult> {
+      const provider = input.provider ?? "gateway";
+      const startedAt = Date.now();
+      await recordAiTelemetry(telemetry, "forge.ai.agent.started", {
+        ...baseProps(),
+        provider,
+        model: input.model,
+        purpose: input.purpose,
+        toolCount: Object.keys(input.tools ?? {}).length,
+      });
+
+      try {
+        if (useMock) {
+          const mock = dequeueMockAiResponse();
+          const usage = createMockAiUsage(mock.usage);
+          const latencyMs = Date.now() - startedAt;
+          const estimatedCostUsd = estimateCostUsd(provider, input.model, usage);
+          const result = {
+            text: mock.text,
+            provider,
+            model: input.model,
+            purpose: input.purpose,
+            usage,
+            latencyMs,
+            toolCalls: [],
+            toolResults: [],
+            steps: 1,
+            estimatedCostUsd,
+          };
+          await recordAiTelemetry(telemetry, "forge.ai.agent.completed", {
+            ...baseProps(),
+            provider,
+            model: input.model,
+            purpose: input.purpose,
+            latencyMs,
+            usage,
+            estimatedCostUsd,
+            status: "completed",
+            mode: "mock",
+          });
+          return result;
+        }
+
+        const languageModel = await resolveLanguageModel(provider, input.model, secrets);
+        const { ToolLoopAgent, hasToolCall, stepCountIs, tool } = await import("ai");
+        const toolRuntimeContext = {
+          secrets,
+          env: options.toolContext?.env ?? {},
+          telemetry,
+          auth: options.toolContext?.auth,
+        };
+
+        const tools = Object.fromEntries(
+          Object.entries(input.tools ?? {}).map(([name, definition]) => {
+            const needsApproval = definition.needsApproval;
+            const aiSdkToolConfig = {
+              description: definition.description,
+              inputSchema: definition.inputSchema as never,
+              ...(definition.outputSchema
+                ? { outputSchema: definition.outputSchema as never }
+                : {}),
+              ...(definition.strict !== undefined ? { strict: definition.strict } : {}),
+              ...(needsApproval !== undefined
+                ? {
+                    needsApproval:
+                      typeof needsApproval === "function"
+                        ? async ({ args }: { args: unknown }) =>
+                            Boolean(await needsApproval(args as never))
+                        : needsApproval,
+                  }
+                : {}),
+              execute: async (args: unknown) => {
+                await recordAiTelemetry(telemetry, "forge.ai.tool.started", {
+                  ...baseProps(),
+                  provider,
+                  model: input.model,
+                  purpose: input.purpose,
+                  tool: name,
+                  risk: definition.risk ?? "external",
+                });
+                const toolStartedAt = Date.now();
+                try {
+                  const output = await definition.handler(
+                    toolRuntimeContext,
+                    args as never,
+                  );
+                  await recordAiTelemetry(telemetry, "forge.ai.tool.completed", {
+                    ...baseProps(),
+                    provider,
+                    model: input.model,
+                    purpose: input.purpose,
+                    tool: name,
+                    latencyMs: Date.now() - toolStartedAt,
+                    status: "completed",
+                  });
+                  return output;
+                } catch (error) {
+                  await recordAiTelemetry(telemetry, "forge.ai.tool.failed", {
+                    ...baseProps(),
+                    provider,
+                    model: input.model,
+                    purpose: input.purpose,
+                    tool: name,
+                    latencyMs: Date.now() - toolStartedAt,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                  });
+                  throw error;
+                }
+              },
+            };
+            return [name, tool(aiSdkToolConfig as never)];
+          }),
+        );
+
+        const stopWhen =
+          input.stopWhen?.kind === "toolCall"
+            ? hasToolCall(input.stopWhen.toolName)
+            : stepCountIs(input.stopWhen?.maxSteps ?? input.maxSteps ?? 20);
+
+        const agent = new ToolLoopAgent({
+          model: languageModel as never,
+          instructions: input.instructions,
+          tools,
+          stopWhen,
+          temperature: input.temperature,
+          maxOutputTokens: input.maxTokens,
+        });
+
+        const result = await agent.generate({ prompt: input.prompt });
+        const usage = mapUsage(result.usage);
+        const latencyMs = Date.now() - startedAt;
+        const estimatedCostUsd = estimateCostUsd(provider, input.model, usage);
+        const raw = result as unknown as {
+          steps?: unknown[];
+          toolCalls?: Array<{ toolName?: string; input?: unknown; args?: unknown }>;
+          toolResults?: Array<{ toolName?: string; output?: unknown; result?: unknown }>;
+        };
+
+        await recordAiTelemetry(telemetry, "forge.ai.agent.completed", {
+          ...baseProps(),
+          provider,
+          model: input.model,
+          purpose: input.purpose,
+          latencyMs,
+          usage,
+          estimatedCostUsd,
+          status: "completed",
+          steps: raw.steps?.length ?? 1,
+        });
+        await recordAiTelemetry(telemetry, "forge.ai.usage", {
+          ...baseProps(),
+          provider,
+          model: input.model,
+          purpose: input.purpose,
+          usage,
+          estimatedCostUsd,
+          method: "runAgent",
+        });
+
+        return {
+          text: result.text,
+          provider,
+          model: input.model,
+          purpose: input.purpose,
+          usage,
+          latencyMs,
+          toolCalls: (raw.toolCalls ?? []).map((call) => ({
+            toolName: call.toolName ?? "unknown",
+            input: call.input ?? call.args,
+          })),
+          toolResults: (raw.toolResults ?? []).map((toolResult) => ({
+            toolName: toolResult.toolName ?? "unknown",
+            output: toolResult.output ?? toolResult.result,
+          })),
+          steps: raw.steps?.length ?? 1,
+          estimatedCostUsd,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await recordAiTelemetry(telemetry, "forge.ai.agent.failed", {
+          ...baseProps(),
+          provider,
+          model: input.model,
+          purpose: input.purpose,
+          status: "failed",
+          error: message,
+        });
+        throw error;
+      }
+    },
   };
 }
 
@@ -390,5 +594,6 @@ export function createNoopAiContext(): AiContext {
     generateText: noop,
     streamText: noop,
     generateStructured: noop,
+    runAgent: noop,
   };
 }