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

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/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/server.ts

@@ -11,11 +11,50 @@ export interface ForgeTelemetry {
   capture(name: string, payload?: Record<string, unknown>): Promise<void> | void;
 }
 
+export type ForgeAiProvider = "openai" | "anthropic" | "gateway";
+
+export interface ForgeAiUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+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 ForgeAgentRuntime {
+  run(input: ForgeRunAgentInput): Promise<ForgeRunAgentResult>;
+}
+
 export interface ForgeContext {
   db: ForgeRecord;
   emit(event: string, payload?: Record<string, unknown>): Promise<void> | void;
   telemetry: ForgeTelemetry;
   secrets: ForgeRecord;
+  agent?: ForgeAgentRuntime;
   auth?: {
     userId?: string;
     tenantId?: string;
@@ -44,6 +83,41 @@ export type ForgeActionDefinition<TEvent = unknown, TResult = unknown> = Record<
   handler: (ctx: ForgeContext, event: TEvent) => TResult | Promise<TResult>;
 };
 
+export type ForgeAiToolRisk = "read" | "write" | "external" | "destructive";
+
+export interface ForgeAiToolRuntimeContext {
+  secrets: ForgeRecord;
+  env: Record<string, string | undefined>;
+  telemetry: ForgeTelemetry;
+  auth?: ForgeContext["auth"];
+}
+
+export type ForgeAiToolDefinition<TArgs = unknown, TResult = unknown> = Record<string, 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 type ForgeAgentDefinition = Record<string, unknown> & {
+  provider?: "openai" | "anthropic" | "gateway";
+  model: string;
+  instructions: string;
+  tools?: Record<string, ForgeAiToolDefinition> | string[];
+  stopWhen?: ForgeAgentStopWhen;
+  maxSteps?: number;
+};
+
 export function defineTable<T extends Record<string, unknown>>(definition: T): T {
   return definition;
 }
@@ -80,6 +154,14 @@ export function action<T extends ForgeActionDefinition>(definition: T): ForgeDef
   return definition;
 }
 
+export function aiTool<T extends ForgeAiToolDefinition>(definition: T): ForgeDefinition<T> {
+  return definition;
+}
+
+export function agent<T extends ForgeAgentDefinition>(definition: T): ForgeDefinition<T> {
+  return definition;
+}
+
 export function event(name: string): { kind: "event"; name: string } {
   return { kind: "event", name };
 }

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.2";
+export const FORGEOS_VERSION = "0.1.0-alpha.3";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;