@studio-foundation/contracts

Studio is a declarative YAML runtime for AI agents. It orchestrates multi-stage agent workflows with structured output validation and automatic retry. This package is contracts: the shared TypeScript types and interfaces that every other Studio package imports. Zero dependencies, zero logic.

contracts is the leaf of the dependency graph. It defines the language all Studio packages speak: PipelineDefinition, StageRun, OutputContract, AgentConfig, LLMRequest, and the rest. Install it if you're writing tooling that reads or produces Studio configs, or if you're embedding Studio packages into your own code and need the types.

• Homepage: https://github.com/studio-foundation/studio
• Full docs: README · INVARIANTS
• Use via the CLI: @studio-foundation/cli

Install

npm install @studio-foundation/contracts
# or
pnpm add @studio-foundation/contracts

Usage

import type {
  PipelineDefinition,
  StageDefinition,
  OutputContract,
  AgentConfig,
  StageStatus,
} from '@studio-foundation/contracts';

import { isStageGroup } from '@studio-foundation/contracts'; // the only runtime export

for (const stage of pipeline.stages) {
  if (isStageGroup(stage)) {
    // handle a group
  } else {
    // handle a plain stage
  }
}

Dependency position

contracts ← ralph
contracts ← runner
contracts ← anonymizer
contracts ← engine
contracts ← cli
contracts ← api

Nothing imports upward. If you find yourself adding a dep here, you're solving the wrong problem.

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 |

Key types

Hooks (pipeline.ts)

// 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)

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)

interface StartupCommand {
  command: string;    // Shell command to run
  inject_as: string;  // Key to inject stdout under
}

Sub-pipeline spawning (spawner.ts)

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.

For contributors

Internal rules that govern this package:

• Zero dependencies: no imports from other @studio-foundation/* packages, ever.
• Zero logic: types and interfaces only. The exceptions are StudioError/ErrorCode in errors.ts and the pure type guards isStageGroup(), isMapStage() and isCallStage() in pipeline.ts (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.

Test coverage target

A line-count ratio is meaningless here: almost everything in src/ is erased at compile time, so counting test files against source files measures nothing. The package has two distinct surfaces and one target each.

| Surface | Target | Enforced by | |---|---|---| | Runtime exports (StudioError, ErrorCode, the three type guards) | 100% statements, branches, functions, lines | pnpm test:coverage thresholds in vitest.config.ts — CI fails below | | Types and interfaces | Every invariant another package relies on has a compile-time assertion | tests/types.test-d.ts, run by vitest --typecheck as part of pnpm test |

100% on the runtime surface is not an aspiration — it is five exports, so anything less means a shipped function nobody ever executed.

For the type surface, "coverage" is not a percentage. The bar is behavioural: a type assertion earns its place only if changing the type breaks it. Before adding one, mutate the type and confirm the test fails — expectTypeOf assertions that can't fail are the most convincing kind of dead test.

License

AGPL-3.0-only