@studio-foundation/contracts 0.3.0-beta.1

package/README.md

@@ -0,0 +1,106 @@
+# @studio-foundation/contracts
+
+Shared TypeScript types and interfaces for the Studio monorepo. Zero dependencies, zero logic.
+
+## Role
+
+`contracts` is the leaf package — every other Studio package imports from it, nothing imports it back. It defines the language that all packages speak.
+
+```
+contracts ← ralph
+contracts ← runner
+contracts ← engine
+contracts ← cli
+```
+
+## What's in here
+
+| Module | Purpose |
+|--------|---------|
+| `pipeline.ts` | `PipelineDefinition`, `StageDefinition`, `StageGroup`, `StageHooks`, `ToolHookDef`, `StageHookDef`, `StartupCommand`, `isStageGroup()` |
+| `stage.ts` | `StageStatus`, `StageKind`, `StageResult` |
+| `task.ts` | `TaskStatus` |
+| `agent.ts` | `AgentConfig`, `AgentProfile`, `ToolCall` (includes `plugins`, `skills`, `anonymize`) |
+| `run.ts` | `PipelineRun`, `StageRun`, `TaskRun`, `AgentRun`, `AgentStatus` |
+| `validation.ts` | `OutputContract`, `ToolCallRequirements`, `ValidationResult`, `ValidationRule` |
+| `provider.ts` | `LLMRequest`, `LLMResponse`, `Message`, `ToolDefinition` |
+| `errors.ts` | `ErrorCode` (enum), `StudioError` |
+| `context-pack.ts` | `ContextPackDefinition`, `ResolvedContextPack` |
+| `tool-plugin.ts` | `ToolPluginDef`, `ToolCommandDef`, `ShellExecute`, `BuiltinExecute`, `ParameterDef` |
+| `runner-events.ts` | `RunnerCallbacks`, `ToolCallStartEvent`, `ToolCallCompleteEvent`, `AgentThinkingEvent`, `AgentProgressEvent`, `AgentTokenEvent` |
+| `spawner.ts` | `RunSpawner`, `SpawnConfig`, `SpawnResult` |
+| `integration-plugin.ts` | `IntegrationPluginDef` |
+
+## Key types
+
+### Hooks (pipeline.ts)
+
+```typescript
+// Stage-level hook (on_stage_start, on_stage_complete)
+interface StageHookDef {
+  command: string;
+  on_failure?: 'warn' | 'reject' | 'fail';  // default: 'warn'
+}
+
+// Tool-level hook (pre_tool_use, post_tool_use)
+interface ToolHookDef {
+  matcher: string;  // exact tool name, e.g. "repo_manager-write_file"
+  command: string;
+  on_failure?: 'warn' | 'reject';
+}
+
+interface StageHooks {
+  on_stage_start?: StageHookDef[];
+  on_stage_complete?: StageHookDef[];
+  pre_tool_use?: ToolHookDef[];
+  post_tool_use?: ToolHookDef[];
+}
+```
+
+### Agent (agent.ts)
+
+```typescript
+interface AgentConfig {
+  name: string;
+  provider: string;
+  model: string;
+  system_prompt?: string;
+  tools?: string[];
+  plugins?: string[];   // Claude Code plugin names
+  skills?: string[];    // .skill.md file names
+  anonymize?: boolean;  // Enable PII anonymization
+}
+```
+
+### on_pipeline_start (pipeline.ts)
+
+```typescript
+interface StartupCommand {
+  command: string;    // Shell command to run
+  inject_as: string;  // Key to inject stdout under
+}
+```
+
+### Sub-pipeline spawning (spawner.ts)
+
+```typescript
+interface RunSpawner {
+  spawnAndWait(config: SpawnConfig): Promise<SpawnResult>;
+}
+
+interface SpawnConfig {
+  pipeline: string;
+  input: Record<string, unknown>;
+  parentRunId: string;
+  depth: number;
+}
+```
+
+Used by the `studio_run` builtin tool to spawn sub-pipelines from within an agent run.
+
+## Rules
+
+- **Zero dependencies** — no imports from other `@studio/*` packages, ever.
+- **Zero logic** — types and interfaces only. The one exception: `isStageGroup()` in `pipeline.ts` is a pure type guard function (no side effects, no state).
+- If you need to add a type used by two packages, put it here.
+- If you're adding logic, you're in the wrong package.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@studio-foundation/contracts",
+  "version": "0.3.0-beta.1",
+  "description": "Shared TypeScript types and interfaces for Studio v7",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "keywords": [
+    "studio",
+    "types",
+    "contracts"
+  ],
+  "author": "Ariane Guay",
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,33 @@
+// Agent configuration and profiles
+
+export interface AgentConfig {
+  name: string;
+  description?: string;
+  provider?: string;
+  model?: string;
+  system_prompt?: string;
+  tools?: string[];
+  plugins?: string[];
+  skills?: string[];
+  temperature?: number;
+  max_tokens?: number;
+  anonymize?: boolean;  // Enable PII anonymization for this agent
+}
+
+/** AgentConfig after defaults have been applied — provider and model are guaranteed. */
+export interface ResolvedAgentConfig extends AgentConfig {
+  provider: string;
+  model: string;
+}
+
+export interface AgentProfile extends AgentConfig {
+  // Additional profile-specific fields
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+}

package/src/context-pack.ts

@@ -0,0 +1,15 @@
+// Shared types for the context packs feature (STU-13)
+
+export interface ContextPackDefinition {
+  name: string;
+  description?: string;
+  version: number;
+  files?: Array<{ path: string }>;
+  inline?: Array<{ title: string; content: string }>;
+}
+
+export interface ResolvedContextPack {
+  name: string;
+  description?: string;
+  sections: Array<{ title: string; content: string }>;
+}

package/src/errors.ts

@@ -0,0 +1,23 @@
+// Error types and codes
+
+export enum ErrorCode {
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  AGENT_EXECUTION_FAILED = 'AGENT_EXECUTION_FAILED',
+  STAGE_FAILED = 'STAGE_FAILED',
+  PIPELINE_FAILED = 'PIPELINE_FAILED',
+  RALPH_EXHAUSTED = 'RALPH_EXHAUSTED',
+  TOOL_EXECUTION_FAILED = 'TOOL_EXECUTION_FAILED',
+  PROVIDER_ERROR = 'PROVIDER_ERROR',
+  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
+}
+
+export class StudioError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'StudioError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Export barrel for @studio/contracts
+// All types are re-exported from their source files
+
+export * from './pipeline.js';
+export * from './stage.js';
+export * from './task.js';
+export * from './agent.js';
+export * from './run.js';
+export * from './validation.js';
+export * from './provider.js';
+export * from './errors.js';
+export * from './context-pack.js';
+export * from './tool-plugin.js';
+
+export * from './runner-events.js';
+
+export * from './spawner.js';
+export * from './integration-plugin.js';

package/src/integration-plugin.ts

@@ -0,0 +1,34 @@
+// contracts/src/integration-plugin.ts
+
+export interface IntegrationPluginDef {
+  name: string;
+  version: number;
+  description?: string;
+  config?: {
+    required?: string[];
+    optional?: Record<string, unknown>;
+  };
+  events?: {
+    consumes?: string[];
+    emits?: string[];
+  };
+  test?: {
+    type: 'http';
+    endpoint: string;
+    method?: 'GET' | 'POST';
+    /** e.g. "bearer:${LINEAR_API_KEY}" — resolved before use */
+    auth?: string;
+    body?: string;
+    expect?: { status?: number };
+  };
+  webhook?: {
+    hmac?: {
+      header: string;       // e.g. 'linear-signature'
+      secret_env: string;   // e.g. 'LINEAR_WEBHOOK_SECRET' — resolved from integration config
+    };
+    handler: string;        // e.g. 'linear-webhook' — key in WEBHOOK_HANDLERS registry
+  };
+  on_failure?: {
+    handler: string;        // e.g. 'linear-failure' — key in FAILURE_HANDLERS registry
+  };
+}

package/src/pipeline.ts

@@ -0,0 +1,97 @@
+// Pipeline and Stage definitions
+
+import type { StageKind } from './stage';
+
+export interface InputField {
+  name: string;
+  type: 'text' | 'array';
+  prompt: string;
+  required: boolean;
+  default?: string;
+  items?: 'text';
+}
+
+export interface InputSchema {
+  type: 'structured';
+  fields: InputField[];
+}
+
+export interface StartupCommand {
+  command: string;
+  inject_as: string;
+}
+
+export interface PipelineDefinition {
+  name: string;
+  description: string;
+  version: number;
+  on_pipeline_start?: StartupCommand[];
+  input_schema?: InputSchema;
+  repo?: {
+    url: string;
+    branch?: string;
+  };
+  stages: PipelineEntry[];
+}
+
+// Lifecycle hooks — configurable shell commands at stage/tool lifecycle points
+
+export type HookOnFailure = 'warn' | 'reject' | 'fail';
+
+export interface StageHookDef {
+  command: string;
+  on_failure?: HookOnFailure;  // default: 'warn'
+}
+
+export interface ToolHookDef {
+  matcher: string;             // exact tool name to match (e.g. "repo_manager-write_file")
+  command: string;
+  on_failure?: 'warn' | 'reject';  // default: 'warn' — 'fail' not supported at tool boundary
+}
+
+export interface StageHooks {
+  on_stage_start?: StageHookDef[];
+  on_stage_complete?: StageHookDef[];
+  pre_tool_use?: ToolHookDef[];
+  post_tool_use?: ToolHookDef[];
+}
+
+export interface StageDefinition {
+  name: string;
+  condition?: string;   // e.g. "input.meals_count >= 6" or "stages.foo.output.count > 0"
+  kind?: StageKind;
+  agent?: string;           // optional — not needed for script executor
+  executor?: 'script';      // 'script' or absent (defaults to LLM)
+  script?: string;          // path to script file (required when executor: 'script')
+  runtime?: 'python' | 'node' | 'shell'; // runtime for script executor
+  timeout_ms?: number;      // script timeout in ms (default: 30000)
+  contract?: string;
+  ralph?: {
+    max_attempts: number;
+    retry_strategy: string;
+    max_tool_calls?: number;
+  };
+  context?: {
+    include: string[];
+    packs?: string[];
+  };
+  tools?: {
+    required?: string[];
+  };
+  hooks?: StageHooks;
+}
+
+// A pipeline entry is either a stage or a group of stages
+export type PipelineEntry = StageDefinition | StageGroup;
+
+export interface StageGroup {
+  group: string;
+  max_iterations: number;
+  mode?: 'sequential' | 'parallel';         // default: 'sequential'
+  on_failure?: 'fail-fast' | 'collect-all'; // parallel only, default: 'fail-fast'
+  stages: StageDefinition[];
+}
+
+export function isStageGroup(entry: PipelineEntry): entry is StageGroup {
+  return 'group' in entry && 'stages' in entry;
+}

package/src/provider.ts

@@ -0,0 +1,39 @@
+// LLM provider interfaces
+
+export interface LLMRequest {
+  model: string;
+  messages: Message[];
+  tools?: ToolDefinition[];
+  temperature?: number;
+  max_tokens?: number;
+  stage_name?: string;
+  json_mode?: boolean;
+}
+
+export interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface LLMResponse {
+  content: string;
+  tool_calls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+  finish_reason: string;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cached_input_tokens?: number;
+    cache_creation_tokens?: number;
+  };
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}

package/src/run.ts

@@ -0,0 +1,49 @@
+// Runtime execution tracking
+
+import type { StageStatus } from './stage';
+import type { TaskStatus } from './task';
+
+export type AgentStatus = 'pending' | 'running' | 'success' | 'failed';
+
+export interface PipelineRun {
+  id: string;
+  pipeline_name: string;
+  status: StageStatus;
+  started_at: string;
+  completed_at?: string;
+  stages: StageRun[];
+  input?: Record<string, unknown>;
+  parent_run_id?: string;
+}
+
+export interface StageRun {
+  id: string;
+  stage_name: string;
+  status: StageStatus;
+  started_at: string;
+  completed_at?: string;
+  tasks: TaskRun[];
+  output?: unknown;  // final output of the stage (populated by engine for observability)
+  skipped_reason?: string;  // reason why stage was skipped (populated by resume loop)
+}
+
+export interface TaskRun {
+  id: string;
+  task_name: string;
+  status: TaskStatus;
+  started_at: string;
+  completed_at?: string;
+  agent_runs: AgentRun[];
+}
+
+export interface AgentRun {
+  id: string;
+  agent_name: string;
+  attempt: number;
+  status: AgentStatus;
+  tool_calls: number;
+  started_at: string;
+  completed_at?: string;
+  output?: unknown;
+  error?: string;
+}

package/src/runner-events.ts

@@ -0,0 +1,69 @@
+/**
+ * Event types for real-time tool call streaming.
+ * Defined in contracts (leaf package) so runner can import them
+ * without creating an inverse dependency on engine.
+ */
+
+export interface ToolCallStartEvent {
+  tool: string;
+  params: Record<string, unknown>;
+  timestamp: number; // ms since epoch (Date.now())
+}
+
+export interface ToolCallCompleteEvent {
+  tool: string;
+  result: unknown; // tool-plugin-specific; typed by each tool plugin
+  error?: string;
+  duration_ms: number;
+  timestamp: number; // ms since epoch (Date.now())
+}
+
+export interface AgentThinkingEvent {
+  thought: string;   // LLM text content emitted before the first round of tool calls
+  timestamp: number; // ms since epoch (Date.now())
+}
+
+export interface AgentProgressEvent {
+  message: string;   // LLM text content emitted between subsequent rounds of tool calls
+  timestamp: number; // ms since epoch (Date.now())
+}
+
+export interface AgentTokenEvent {
+  token: string;
+  timestamp: number; // ms since epoch (Date.now())
+}
+
+/**
+ * Subset of callbacks the runner accepts for real-time event emission.
+ * Engine populates these from EngineEvents and passes them to runAgent().
+ */
+export interface RunnerCallbacks {
+  onToolCallStart?: (event: ToolCallStartEvent) => void;
+  onToolCallComplete?: (event: ToolCallCompleteEvent) => void;
+  onAgentThinking?: (event: AgentThinkingEvent) => void;
+  onAgentProgress?: (event: AgentProgressEvent) => void;
+  onAgentToken?: (event: AgentTokenEvent) => void;
+
+  /**
+   * Called before tool execution. Return { blocked: true, error } to prevent the tool from running.
+   * The error is surfaced as the tool result so the LLM can react and RALPH loop continues.
+   */
+  onPreToolUse?: (event: {
+    tool: string;
+    params: Record<string, unknown>;
+    timestamp: number;
+  }) => Promise<{ blocked: boolean; error?: string }>;
+
+  /**
+   * Called after tool execution (only if the tool was not blocked).
+   * Return { append_message } to inject a note into the conversation after the tool result.
+   * Only effective in the standard (Chat Completions) provider path.
+   */
+  onPostToolUse?: (event: {
+    tool: string;
+    params: Record<string, unknown>;
+    result: unknown;
+    error?: string;
+    timestamp: number;
+  }) => Promise<{ append_message?: string }>;
+}

package/src/spawner.ts

@@ -0,0 +1,19 @@
+// The abstraction that studio-run tool uses to launch child runs.
+// Implementations: DirectEngineSpawner (engine) and HttpApiSpawner (api).
+
+export interface SpawnConfig {
+  pipeline: string;
+  input: Record<string, unknown>;
+  parentRunId: string;
+  depth: number;
+}
+
+export interface SpawnResult {
+  run_id: string;
+  status: string;
+  output: unknown;
+}
+
+export interface RunSpawner {
+  spawnAndWait(config: SpawnConfig): Promise<SpawnResult>;
+}

package/src/stage.ts

@@ -0,0 +1,13 @@
+// Stage status and results
+
+export type StageStatus = 'pending' | 'running' | 'success' | 'failed' | 'skipped' | 'rejected' | 'cancelled';
+
+export type StageKind = string;
+
+export interface StageResult {
+  status: StageStatus;
+  output?: unknown;
+  error?: string;
+  attempts: number;
+  duration_ms: number;
+}

package/src/task.ts

@@ -0,0 +1,3 @@
+// Task status — used internally by run.ts (TaskRun.status)
+
+export type TaskStatus = 'pending' | 'running' | 'success' | 'failed';

package/src/tool-plugin.ts

@@ -0,0 +1,47 @@
+// contracts/src/tool-plugin.ts
+
+export type ParseOutputFormat = 'text' | 'json';
+
+export interface ParameterDef {
+  type: 'string' | 'number' | 'boolean' | 'array';
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+  items?: { type: string };
+}
+
+export interface ShellExecute {
+  type: 'shell';
+  command: string;
+  parse_output?: ParseOutputFormat;
+  timeout_ms?: number;
+}
+
+export interface BuiltinExecute {
+  type: 'builtin';
+  handler?: string;  // informational only — we look up by cmd.name
+  parse_output?: ParseOutputFormat;
+}
+
+export type CommandExecute = ShellExecute | BuiltinExecute;
+
+export interface ToolCommandDef {
+  name: string;
+  description: string;
+  parameters: Record<string, ParameterDef>;
+  execute: CommandExecute;
+  constraints?: Record<string, unknown>;
+}
+
+export interface ToolPluginDef {
+  name: string;
+  description?: string;
+  version: number;
+  commands: ToolCommandDef[];
+  config?: Record<string, unknown>;
+  prompt_snippet?: string;
+  constraints?: {
+    requires_initialized_repo?: boolean;
+    requires_binaries?: string[];
+  };
+}

package/src/validation.ts

@@ -0,0 +1,42 @@
+// Validation contracts and results
+
+export interface ToolCallRequirements {
+  minimum?: number;
+  maximum?: number;
+  required_tools?: string[];
+  required_tool_groups?: string[][];
+  counted_tools?: string[];
+}
+
+export interface OutputContract {
+  name: string;
+  version: number;
+  schema?: {
+    required_fields?: string[];
+    [key: string]: unknown;
+  };
+  tool_calls?: ToolCallRequirements;
+  custom_rules?: ValidationRule[];
+  post_validation?: {
+    rejection_detection: {
+      field: string;
+      rejected_values?: string[];
+      approved_values?: string[];
+      details_field?: string;
+      summary_field?: string;
+      reject_if_non_empty?: string;
+    };
+  };
+}
+
+export interface ValidationRule {
+  name: string;
+  description: string;
+  check: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}