forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/review/types.ts

@@ -1,5 +1,6 @@
 import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 import type { ImpactedSystems, ImpactSource } from "../impact/types.ts";
+import type { CategorizedFileSummary, ChangeType, DiffPlan } from "../workspace/change-summary.ts";
 
 export type ReviewSubcommand = "run" | "inspect" | "list" | "explain";
 export type ReviewMode = "quick" | "standard" | "strict";
@@ -26,6 +27,7 @@ export interface ReviewCommandOptions {
   json: boolean;
   md: boolean;
   sarif: boolean;
+  full?: boolean;
   write: boolean;
   changed: boolean;
   staged: boolean;
@@ -60,6 +62,16 @@ export interface ReviewChanged {
   deployFiles: string[];
 }
 
+export interface ReviewFocus {
+  first: "authoredChanges";
+  then: "derivedArtifacts";
+  generatedIsDerived: boolean;
+  suggestedOrder: ChangeType[];
+  summary: string;
+}
+
+export type ReviewDiffPlan = DiffPlan;
+
 export interface ReviewSummary {
   title: string;
   bullets: string[];
@@ -130,6 +142,9 @@ export interface ReviewReport {
   risk: ReviewRisk;
   findings: ReviewFinding[];
   changed: ReviewChanged;
+  changeSummary: CategorizedFileSummary;
+  reviewFocus: ReviewFocus;
+  diffPlan: ReviewDiffPlan;
   impacted: ImpactedSystems;
   checks: ReviewCheckResult[];
   recommendedCommands: string[];

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,
   };
 }

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

@@ -51,10 +51,80 @@ 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>;
+}
+
+export interface AgentRuntimeContext {
+  run(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
 }
 
 export interface AiTelemetryEnvelope {

package/src/forge/runtime/auth/claims.ts

@@ -1,4 +1,5 @@
 import {
+  FORGE_AUTH_CLAIM_INVALID,
   FORGE_AUTH_CLAIM_MISSING,
   FORGE_AUTH_TENANT_MISSING,
 } from "../../compiler/diagnostics/codes.ts";
@@ -57,6 +58,31 @@ function asStringArray(value: unknown): string[] {
   return [];
 }
 
+function claimExists(claims: Record<string, unknown>, path: string | undefined): boolean {
+  return getClaimValue(claims, path) !== undefined;
+}
+
+function validateRoleClaim(
+  claims: Record<string, unknown>,
+  path: string | undefined,
+  label: string,
+): void {
+  const value = getClaimValue(claims, path);
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value === "string") {
+    return;
+  }
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return;
+  }
+  throw new ForgeAuthError(
+    FORGE_AUTH_CLAIM_INVALID,
+    `auth claim '${path ?? label}' must be a string or string array`,
+  );
+}
+
 function uniqueSorted(values: string[]): string[] {
   return [...new Set(values)].sort();
 }
@@ -84,6 +110,12 @@ export function mapClaimsToAuthContext(
     );
   }
 
+  if (claimExists(payload, mapping.role)) {
+    validateRoleClaim(payload, mapping.role, "role");
+  }
+  if (claimExists(payload, mapping.roles)) {
+    validateRoleClaim(payload, mapping.roles, "roles");
+  }
   const role = asString(getClaimValue(payload, mapping.role));
   const roles = uniqueSorted([
     ...(role ? [role] : []),

package/src/forge/runtime/auth/errors.ts

@@ -1,4 +1,5 @@
 import {
+  FORGE_AUTH_CLAIM_INVALID,
   FORGE_AUTH_CLAIM_MISSING,
   FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION,
   FORGE_AUTH_DISABLED,
@@ -20,6 +21,7 @@ export type ForgeAuthDiagnosticCode =
   | typeof FORGE_AUTH_TOKEN_EXPIRED
   | typeof FORGE_AUTH_JWKS_FAILED
   | typeof FORGE_AUTH_CLAIM_MISSING
+  | typeof FORGE_AUTH_CLAIM_INVALID
   | typeof FORGE_AUTH_TENANT_MISSING
   | typeof FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION
   | typeof FORGE_AUTH_MODE_INVALID

package/src/forge/runtime/context/create-context.ts

@@ -13,7 +13,7 @@ import { loadEnvFiles } from "../secrets/env-loader.ts";
 import { loadEnvSchema, loadSecretRegistry } from "../secrets/check.ts";
 import { createRuntimeSecretsBundle } from "../secrets/runtime-bundle.ts";
 import { createAiContext } from "../ai/context.ts";
-import type { AiContext } from "../ai/types.ts";
+import type { AgentRuntimeContext, AiContext } from "../ai/types.ts";
 import { isMockAiEnabled } from "../ai/state.ts";
 import { currentReleaseInfo, type RuntimeReleaseInfo } from "../release/runtime.ts";
 
@@ -26,6 +26,7 @@ export interface ForgeContext {
   secrets: SecretsContext;
   config: ConfigContext;
   ai: AiContext;
+  agent: AgentRuntimeContext;
   release: RuntimeReleaseInfo;
 }
 
@@ -67,11 +68,16 @@ function buildSecretsConfigAndAi(
   runtimeKind: RuntimeContext,
   store: RuntimeEnvStore,
   telemetry: TelemetryContext,
-  options?: { mockAi?: boolean },
+  options?: {
+    mockAi?: boolean;
+    auth?: AuthContext;
+    env?: Record<string, string | undefined>;
+  },
 ): {
   secrets: SecretsContext;
   config: ConfigContext;
   ai: AiContext;
+  agent: AgentRuntimeContext;
   env: Record<string, string | undefined>;
 } {
   const registry = workspaceRoot ? loadSecretRegistry(workspaceRoot) : null;
@@ -93,12 +99,20 @@ function buildSecretsConfigAndAi(
       tenantId:
         undefined,
     },
+    toolContext: {
+      env: options?.env ?? store.snapshot(),
+      auth: options?.auth,
+    },
   });
+  const agent: AgentRuntimeContext = {
+    run: (input) => ai.runAgent(input),
+  };
 
   return {
     secrets: bundle.secrets,
     config: bundle.config,
     ai,
+    agent,
     env: store.snapshot(),
   };
 }
@@ -123,12 +137,16 @@ export function createForgeContext(
     (options?.workspaceRoot
       ? getRuntimeEnvStore(options.workspaceRoot)
       : getRuntimeEnvStore());
-  const { secrets, config, ai, env } = buildSecretsConfigAndAi(
+  const { secrets, config, ai, agent, env } = buildSecretsConfigAndAi(
     options?.workspaceRoot,
     runtimeKind,
     store,
     telemetry,
-    { mockAi: options?.mockAi },
+    {
+      mockAi: options?.mockAi,
+      auth,
+      env: options?.env,
+    },
   );
 
   return {
@@ -139,6 +157,7 @@ export function createForgeContext(
     secrets,
     config,
     ai,
+    agent,
     release: currentReleaseInfo(),
     emit: async (eventType, payload) => {
       const enriched =
@@ -178,12 +197,16 @@ export function createActionContext(
     (options?.workspaceRoot
       ? getRuntimeEnvStore(options.workspaceRoot)
       : getRuntimeEnvStore());
-  const { secrets, config, ai, env } = buildSecretsConfigAndAi(
+  const { secrets, config, ai, agent, env } = buildSecretsConfigAndAi(
     options?.workspaceRoot,
     runtimeKind,
     store,
     telemetry,
-    { mockAi: options?.mockAi },
+    {
+      mockAi: options?.mockAi,
+      auth,
+      env: options?.env,
+    },
   );
 
   return {
@@ -194,6 +217,7 @@ export function createActionContext(
     secrets,
     config,
     ai,
+    agent,
     release: currentReleaseInfo(),
     emit: async () => {
       /* actions invoked by outbox worker do not emit */

package/src/forge/runtime/db/generated-client.ts

@@ -37,6 +37,10 @@ export interface GeneratedDbClientOptions {
   writeTracker?: WriteTracker;
 }
 
+function camelCase(value: string): string {
+  return value.replace(/[_-]([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase());
+}
+
 function quoteIdent(ident: string): string {
   return `"${ident.replace(/"/g, '""')}"`;
 }
@@ -286,8 +290,15 @@ export function createGeneratedDbClient(
 ): DbClient {
   const client: DbClient = {};
 
-  for (const [tableName, entry] of Object.entries(tableMap).sort()) {
-    client[tableName] = createTableClient(tx, tableName, entry, options);
+  for (const [accessName, entry] of Object.entries(tableMap).sort()) {
+    const tableClient = createTableClient(tx, entry.tableName, entry, options);
+    client[accessName] = tableClient;
+
+    for (const alias of new Set([camelCase(accessName), camelCase(entry.tableName)])) {
+      if (alias && client[alias] === undefined) {
+        client[alias] = tableClient;
+      }
+    }
   }
 
   return client;

package/src/forge/runtime/db/memory-adapter.ts

@@ -656,9 +656,9 @@ export class MemoryAdapter implements DbAdapter {
       return { rows: [], rowCount: before - table.rows.length };
     }
 
-    const id = params[0];
+    const rowsToDelete = new Set(this.filterRows(table.rows, sql, params));
     const before = table.rows.length;
-    table.rows = table.rows.filter((row) => row.id !== id);
+    table.rows = table.rows.filter((row) => !rowsToDelete.has(row));
     return { rows: [], rowCount: before - table.rows.length };
   }
 

package/src/forge/runtime/db/pglite-adapter.ts

@@ -1,4 +1,6 @@
 import { PGlite } from "@electric-sql/pglite";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import type { DbAdapter, DbQueryResult, DbTransaction } from "./adapter.ts";
 
 function toQueryResult(result: {
@@ -45,7 +47,80 @@ export class PgliteAdapter implements DbAdapter {
 }
 
 export async function createPgliteAdapter(dataDir: string): Promise<DbAdapter> {
+  mkdirSync(dataDir, { recursive: true });
+  repairStalePgliteStore(dataDir);
   const adapter = new PgliteAdapter(dataDir);
-  await adapter.query("SELECT 1");
-  return adapter;
+  try {
+    await adapter.query("SELECT 1");
+    return adapter;
+  } catch (error) {
+    await adapter.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+function repairStalePgliteStore(dataDir: string): void {
+  const pidPath = join(dataDir, "postmaster.pid");
+  if (!existsSync(pidPath)) {
+    return;
+  }
+
+  const rawPid = readFileSync(pidPath, "utf8").split(/\r?\n/, 1)[0]?.trim();
+  const pid = rawPid ? Number(rawPid) : NaN;
+  const stale =
+    !Number.isInteger(pid) ||
+    pid <= 0 ||
+    !isProcessAlive(pid);
+
+  if (!stale) {
+    return;
+  }
+
+  removeStalePgliteLocks(dataDir);
+}
+
+function removeStalePgliteLocks(dataDir: string): void {
+  for (const file of [
+    "postmaster.pid",
+    ".s.PGSQL.5432.lock",
+    ".s.PGSQL.5432.lock.out",
+  ]) {
+    try {
+      unlinkSync(join(dataDir, file));
+    } catch {
+      // Best effort. If PGlite still cannot open, the caller reports the real open error.
+    }
+  }
+}
+
+export function archivePgliteStore(dataDir: string, reason = "repair"): string | null {
+  if (!existsSync(dataDir)) {
+    return null;
+  }
+
+  const parent = dirname(dataDir);
+  const backupsDir = join(parent, `${basename(dataDir)}.backups`);
+  mkdirSync(backupsDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = join(backupsDir, `${basename(dataDir)}.${reason}.${stamp}`);
+
+  try {
+    renameSync(dataDir, backupPath);
+    mkdirSync(dataDir, { recursive: true });
+    return backupPath;
+  } catch {
+    rmSync(join(dataDir, "postmaster.pid"), { force: true });
+    rmSync(join(dataDir, ".s.PGSQL.5432.lock"), { force: true });
+    rmSync(join(dataDir, ".s.PGSQL.5432.lock.out"), { force: true });
+    return null;
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
 }