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

package/src/forge/compiler/ai-registry/parse.ts

@@ -1,7 +1,7 @@
 import type { ForgeAiProvider } from "../types/ai-registry.ts";
 
 const AI_METHOD_PATTERN =
-  /(?:ctx\.ai|ai)\.(generateText|streamText|generateStructured)\s*\(/g;
+  /(?:(?:ctx\.ai|ai)\.(generateText|streamText|generateStructured|runAgent)|ctx\.agent\.(run))\s*\(/g;
 
 const PROVIDER_PATTERN =
   /provider\s*:\s*["'](openai|anthropic|gateway)["']/;
@@ -11,7 +11,7 @@ const MODEL_PATTERN = /model\s*:\s*["']([^"']+)["']/;
 const PURPOSE_PATTERN = /purpose\s*:\s*["']([^"']+)["']/;
 
 export interface ParsedAiCall {
-  method: "generateText" | "streamText" | "generateStructured";
+  method: "generateText" | "streamText" | "generateStructured" | "runAgent";
   provider?: ForgeAiProvider;
   model?: string;
   purpose?: string;
@@ -21,7 +21,7 @@ export function parseAiCallsFromSlice(sourceSlice: string): ParsedAiCall[] {
   const calls: ParsedAiCall[] = [];
 
   for (const match of sourceSlice.matchAll(AI_METHOD_PATTERN)) {
-    const method = match[1] as ParsedAiCall["method"];
+    const method = (match[1] ?? (match[2] ? "runAgent" : "")) as ParsedAiCall["method"];
     const start = match.index ?? 0;
     const window = sourceSlice.slice(start, start + 600);
 
@@ -49,8 +49,102 @@ export function parseAiCallsFromSlice(sourceSlice: string): ParsedAiCall[] {
   return calls;
 }
 
-const FORBIDDEN_AI_CONTEXT_PATTERN = /ctx\.ai\./;
+const FORBIDDEN_AI_CONTEXT_PATTERN = /ctx\.(?:ai\.|agent\.run\s*\()/;
 
 export function detectCtxAiUsage(sourceSlice: string): boolean {
   return FORBIDDEN_AI_CONTEXT_PATTERN.test(sourceSlice);
 }
+
+const DESCRIPTION_PATTERN = /description\s*:\s*["'`]([^"'`]+)["'`]/;
+const RISK_PATTERN = /risk\s*:\s*["'](read|write|external|destructive)["']/;
+const STRICT_PATTERN = /strict\s*:\s*(true|false)/;
+const NEEDS_APPROVAL_PATTERN = /needsApproval\s*:\s*(true|false|async\s*\(|\([^)]*\)\s*=>|[A-Za-z_$][A-Za-z0-9_$]*)/;
+const INSTRUCTIONS_PATTERN = /instructions\s*:\s*["'`]([^"'`]+)["'`]/;
+const TOOL_ARRAY_PATTERN = /tools\s*:\s*\[([^\]]*)\]/s;
+const TOOL_OBJECT_PATTERN = /tools\s*:\s*\{([^}]*)\}/s;
+const STOP_TOOL_PATTERN = /stopWhen\s*:\s*\{[^}]*kind\s*:\s*["']toolCall["'][^}]*toolName\s*:\s*["']([^"']+)["'][^}]*\}/s;
+const STOP_STEP_PATTERN = /stopWhen\s*:\s*\{[^}]*kind\s*:\s*["']stepCount["'][^}]*maxSteps\s*:\s*(\d+)[^}]*\}/s;
+const MAX_STEPS_PATTERN = /maxSteps\s*:\s*(\d+)/;
+
+export interface ParsedAiToolMeta {
+  description?: string;
+  risk: "read" | "write" | "external" | "destructive" | "unknown";
+  strict: boolean;
+  needsApproval: boolean | "dynamic";
+}
+
+export interface ParsedAiAgentMeta {
+  provider?: ForgeAiProvider;
+  model?: string;
+  instructions?: string;
+  tools: string[];
+  stopWhen:
+    | { kind: "stepCount"; maxSteps: number }
+    | { kind: "toolCall"; toolName: string }
+    | { kind: "default" };
+}
+
+function parseBooleanOrDynamic(value: string | undefined): boolean | "dynamic" {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return "dynamic";
+}
+
+function parseStringList(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return [...raw.matchAll(/["'`]([^"'`]+)["'`]/g)]
+    .map((match) => match[1] ?? "")
+    .filter(Boolean)
+    .sort();
+}
+
+function parseObjectToolKeys(raw: string | undefined): string[] {
+  if (!raw) return [];
+  const explicit = [...raw.matchAll(/([A-Za-z_$][A-Za-z0-9_$]*)\s*:/g)]
+    .map((match) => match[1] ?? "")
+    .filter(Boolean);
+  const shorthand = raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(part));
+  return [...new Set([...explicit, ...shorthand])].sort();
+}
+
+export function parseAiToolMeta(sourceSlice: string): ParsedAiToolMeta {
+  const description = DESCRIPTION_PATTERN.exec(sourceSlice)?.[1];
+  const risk = RISK_PATTERN.exec(sourceSlice)?.[1] as ParsedAiToolMeta["risk"] | undefined;
+  const strict = STRICT_PATTERN.exec(sourceSlice)?.[1] === "true";
+  const needsApprovalMatch = NEEDS_APPROVAL_PATTERN.exec(sourceSlice)?.[1];
+
+  return {
+    ...(description ? { description } : {}),
+    risk: risk ?? "unknown",
+    strict,
+    needsApproval: needsApprovalMatch
+      ? parseBooleanOrDynamic(needsApprovalMatch)
+      : false,
+  };
+}
+
+export function parseAiAgentMeta(sourceSlice: string): ParsedAiAgentMeta {
+  const provider = PROVIDER_PATTERN.exec(sourceSlice)?.[1] as ForgeAiProvider | undefined;
+  const model = MODEL_PATTERN.exec(sourceSlice)?.[1];
+  const instructions = INSTRUCTIONS_PATTERN.exec(sourceSlice)?.[1];
+  const arrayTools = parseStringList(TOOL_ARRAY_PATTERN.exec(sourceSlice)?.[1]);
+  const objectTools = parseObjectToolKeys(TOOL_OBJECT_PATTERN.exec(sourceSlice)?.[1]);
+  const stopTool = STOP_TOOL_PATTERN.exec(sourceSlice)?.[1];
+  const stopStepsRaw =
+    STOP_STEP_PATTERN.exec(sourceSlice)?.[1] ?? MAX_STEPS_PATTERN.exec(sourceSlice)?.[1];
+
+  return {
+    ...(provider ? { provider } : {}),
+    ...(model ? { model } : {}),
+    ...(instructions ? { instructions } : {}),
+    tools: [...new Set([...arrayTools, ...objectTools])].sort(),
+    stopWhen: stopTool
+      ? { kind: "toolCall", toolName: stopTool }
+      : stopStepsRaw
+        ? { kind: "stepCount", maxSteps: Number(stopStepsRaw) }
+        : { kind: "default" },
+  };
+}

package/src/forge/compiler/app-graph/forge-apis.ts

@@ -13,6 +13,7 @@ export const FORGE_BUILDER_APIS: Readonly<Record<string, ForgeKind>> = {
   definePolicies: "policy",
   workflow: "workflow",
   agent: "agent",
+  aiTool: "aiTool",
   telemetryEvent: "telemetryEvent",
 };
 

package/src/forge/compiler/dev-manifest/build.ts

@@ -61,6 +61,9 @@ function buildRoutes(
     { method: "GET", path: "/health", purpose: "health" },
     { method: "GET", path: "/entries", purpose: "entries" },
     { method: "GET", path: "/queries", purpose: "queries" },
+    { method: "POST", path: "/ai/agents/chat", purpose: "ai-agent-chat" },
+    { method: "POST", path: "/ai/agents/run", purpose: "ai-agent-run" },
+    { method: "GET", path: "/ai/providers", purpose: "ai-providers" },
     { method: "GET", path: "/workflows", purpose: "workflows" },
     { method: "GET", path: "/workflows/runs", purpose: "workflow-runs" },
     { method: "POST", path: "/workflows/process", purpose: "workflow-process" },

package/src/forge/compiler/make-registry/build.ts

@@ -34,6 +34,7 @@ export function buildMakeRegistry(generatorVersion: string): MakeRegistryArtifac
       "forge make list --json",
       "forge make explain <primitive> --json",
       "forge make ui --framework vite --dry-run --json",
+      "forge make ai-chat support --dry-run --json",
       "forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json",
       "forge make resource <name> --fields title:text --with-ui --yes",
       "forge make apply <planId>",
@@ -123,6 +124,17 @@ export function buildMakeRegistry(generatorVersion: string): MakeRegistryArtifac
         modifies: [],
         examples: ["forge make ui --framework vite --yes"],
       },
+      {
+        name: "ai-chat",
+        summary: "Add a Forge AI agent and React chat component backed by /ai/agents/run.",
+        creates: [
+          "src/ai/<name>Agent.ts",
+          "web/components/<Name>AiChat.tsx",
+          "web/app/<name>-ai/page.tsx when web/app exists",
+        ],
+        modifies: [],
+        examples: ["forge make ai-chat support --yes"],
+      },
       {
         name: "resource",
         summary: "Add schema, policies, CRUD, queries, liveQuery, optional UI, and tests.",
@@ -155,6 +167,7 @@ export function buildMakeTemplates(): MakeTemplateArtifact {
       { name: "component", sourceKind: "frontend", outputPattern: "web/components/<name>.tsx" },
       { name: "page", sourceKind: "frontend", outputPattern: "web/app/<route>/page.tsx" },
       { name: "ui", sourceKind: "frontend", outputPattern: "web/src/App.tsx" },
+      { name: "ai-chat", sourceKind: "frontend", outputPattern: "web/components/<name>AiChat.tsx" },
       { name: "placeholder-test", sourceKind: "test", outputPattern: "tests/make-generated/<name>.test.ts" },
     ],
   };

package/src/forge/compiler/orchestrator/plan.ts

@@ -54,6 +54,8 @@ import { buildDevManifest } from "../dev-manifest/build.ts";
 import { buildRuntimeGraph } from "../runtime-graph/build.ts";
 import {
   buildAgentContractArtifacts,
+  serializeAgentToolRegistryJson,
+  serializeAgentToolRegistryTs,
   serializeCapabilityMapJson,
   serializeCapabilityMapTs,
   serializeAgentContractJson,
@@ -399,6 +401,15 @@ export function plan(input: PlanInput): EmitPlan {
       serializeAgentContractJson(agentArtifacts.contract),
     ),
     makeEmitFile(`${GENERATED_DIR}/appMap.md`, agentArtifacts.appMapMd),
+    makeEmitFile(
+      `${GENERATED_DIR}/agentTools.ts`,
+      serializeAgentToolRegistryTs(agentArtifacts.toolRegistry),
+    ),
+    makeEmitFile(
+      `${GENERATED_DIR}/agentTools.json`,
+      serializeAgentToolRegistryJson(agentArtifacts.toolRegistry),
+    ),
+    makeEmitFile(`${GENERATED_DIR}/agentTools.md`, agentArtifacts.agentToolsMd),
     makeEmitFile(
       `${GENERATED_DIR}/capabilityMap.ts`,
       serializeCapabilityMapTs(agentArtifacts.capabilityMap),

package/src/forge/compiler/orchestrator/serialize.ts

@@ -680,6 +680,8 @@ export function serializeAiRegistryJson(registry: import("../types/ai-registry.t
     inputHash: registry.inputHash,
     providers: registry.providers,
     generations: registry.generations,
+    tools: registry.tools,
+    agents: registry.agents,
     diagnostics: registry.diagnostics,
   };
   return serializeCanonical(payload);
@@ -762,10 +764,76 @@ export interface ForgeGenerateStructuredInput<T> {
   schema: ForgeFlexibleSchema<T>;
 }
 
+export type ForgeAiToolRisk = "read" | "write" | "external" | "destructive";
+
+export interface ForgeAiToolRuntimeContext {
+  secrets: {
+    get(name: string): string;
+    optional(name: string): string | undefined;
+    has(name: string): boolean;
+  };
+  env: Record<string, string | undefined>;
+  telemetry?: {
+    traceId?: string;
+    capture(name: string, properties?: Record<string, unknown>): Promise<void>;
+  };
+  auth?: unknown;
+}
+
+export interface ForgeAiToolDefinition<TArgs = unknown, TResult = unknown> {
+  description: string;
+  inputSchema: unknown;
+  outputSchema?: unknown;
+  strict?: boolean;
+  needsApproval?: boolean | ((args: TArgs) => boolean | Promise<boolean>);
+  risk?: ForgeAiToolRisk;
+  handler: (
+    ctx: ForgeAiToolRuntimeContext,
+    args: TArgs,
+  ) => TResult | Promise<TResult>;
+}
+
+export type ForgeAgentStopWhen =
+  | { kind: "stepCount"; maxSteps: number }
+  | { kind: "toolCall"; toolName: string };
+
+export interface ForgeRunAgentInput {
+  provider?: ForgeAiProvider;
+  model: string;
+  prompt: string;
+  instructions: string;
+  purpose?: string;
+  tools?: Record<string, ForgeAiToolDefinition>;
+  stopWhen?: ForgeAgentStopWhen;
+  maxSteps?: number;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface ForgeRunAgentResult {
+  text: string;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  usage: ForgeAiUsage;
+  latencyMs: number;
+  toolCalls: Array<{
+    toolName: string;
+    input: unknown;
+  }>;
+  toolResults: Array<{
+    toolName: string;
+    output: unknown;
+  }>;
+  steps: number;
+  estimatedCostUsd?: number;
+}
+
 export interface AiContext {
   generateText(input: ForgeGenerateTextInput): Promise<ForgeGenerateTextResult>;
   streamText(input: ForgeStreamTextInput): Promise<ForgeStreamTextResult>;
   generateStructured<T>(input: ForgeGenerateStructuredInput<T>): Promise<T>;
+  runAgent(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
 }
 `;
 }

package/src/forge/compiler/types/ai-registry.ts

@@ -18,10 +18,32 @@ export interface AiGenerationCall {
   provider: ForgeAiProvider;
   model: string;
   purpose?: string;
-  method: "generateText" | "streamText" | "generateStructured";
+  method: "generateText" | "streamText" | "generateStructured" | "runAgent";
   file: string;
 }
 
+export interface AiToolDefinition {
+  name: string;
+  file: string;
+  description?: string;
+  risk: "read" | "write" | "external" | "destructive" | "unknown";
+  strict: boolean;
+  needsApproval: boolean | "dynamic";
+}
+
+export interface AiAgentDefinition {
+  name: string;
+  file: string;
+  provider: ForgeAiProvider;
+  model: string;
+  instructions?: string;
+  tools: string[];
+  stopWhen:
+    | { kind: "stepCount"; maxSteps: number }
+    | { kind: "toolCall"; toolName: string }
+    | { kind: "default" };
+}
+
 export interface AiRegistry {
   schemaVersion: string;
   generatorVersion: string;
@@ -29,5 +51,7 @@ export interface AiRegistry {
   inputHash: string;
   providers: AiProviderDefinition[];
   generations: AiGenerationCall[];
+  tools: AiToolDefinition[];
+  agents: AiAgentDefinition[];
   diagnostics: unknown[];
 }

package/src/forge/compiler/types/app-graph.ts

@@ -12,6 +12,7 @@ export type ForgeKind =
   | "policy"
   | "workflow"
   | "agent"
+  | "aiTool"
   | "telemetryEvent";
 
 export interface ForgeSymbol {

package/src/forge/compiler/types/cli.ts

@@ -79,6 +79,7 @@ export type InspectTarget =
   | "test-graph"
   | "test-plans"
   | "agent-contract"
+  | "agent-tools"
   | "agent-adapters"
   | "capability-map"
   | "framework"

package/src/forge/compiler/types/dev-manifest.ts

@@ -11,6 +11,9 @@ export interface DevRoute {
     | "workflows"
     | "workflow-runs"
     | "workflow-process"
+    | "ai-agent-chat"
+    | "ai-agent-run"
+    | "ai-providers"
     | "queries"
     | "query";
   entryName?: string;