@studio-foundation/contracts 0.3.0-beta.1 → 0.3.0-beta.6

package/dist/tool-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-plugin.js","sourceRoot":"","sources":["../src/tool-plugin.ts"],"names":[],"mappings":"AAAA,+BAA+B"}

package/dist/validation.d.ts

@@ -0,0 +1,38 @@
+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[];
+}
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,eAAe,CAAC,EAAE;QAChB,mBAAmB,EAAE;YACnB,KAAK,EAAE,MAAM,CAAC;YACd,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;YAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;SAC9B,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/validation.js

@@ -0,0 +1,3 @@
+// Validation contracts and results
+export {};
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,mCAAmC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studio-foundation/contracts",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.6",
   "description": "Shared TypeScript types and interfaces for Studio v7",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,9 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "studio",
     "types",

package/.claude/settings.json

@@ -1,5 +0,0 @@
-{
-  "enabledPlugins": {
-    "linear@claude-plugins-official": true
-  }
-}

package/ARCHITECTURE.md

@@ -1,33 +0,0 @@
-# @studio-foundation/contracts
-
-Types et interfaces partagés par tous les packages Studio. ZERO dépendances. ZERO logique.
-
-## Règles
-
-- Ce package n'a AUCUNE dépendance (pas de `@studio/*`, pas de libs externes)
-- JAMAIS de logique — uniquement des types, interfaces, enums TypeScript
-- Exception unique : `isStageGroup()` dans `pipeline.ts` (type guard pur, sans état)
-- Tout changement ici impacte TOUS les autres packages — être conservateur
-- Exporter tout depuis `index.ts`
-
-## Fichiers clés
-
-- `pipeline.ts` — `PipelineDefinition`, `StageDefinition`, `StageGroup`, `StageHooks`, `ToolHookDef`, `StageHookDef`, `StartupCommand`, `isStageGroup()`
-- `stage.ts` — `StageStatus`, `StageKind` (= string), `StageResult`
-- `task.ts` — `TaskStatus`
-- `agent.ts` — `AgentConfig`, `AgentProfile`, `ToolCall`
-- `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`, événements de streaming tool calls et tokens
-- `spawner.ts` — `RunSpawner`, `SpawnConfig`, `SpawnResult`
-- `integration-plugin.ts` — `IntegrationPluginDef`
-
-## Test
-
-```bash
-pnpm test
-```

package/src/agent.ts

@@ -1,33 +0,0 @@
-// 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

@@ -1,15 +0,0 @@
-// 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

@@ -1,23 +0,0 @@
-// 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/integration-plugin.ts

@@ -1,34 +0,0 @@
-// 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

@@ -1,97 +0,0 @@
-// 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

@@ -1,39 +0,0 @@
-// 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

@@ -1,49 +0,0 @@
-// 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

@@ -1,69 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-// 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/tool-plugin.ts

@@ -1,47 +0,0 @@
-// 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

@@ -1,42 +0,0 @@
-// 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[];
-}

package/tests/types.test.ts

@@ -1,101 +0,0 @@
-// Type-level tests for @studio/contracts
-// These tests verify that types compile correctly
-
-import { describe, it, expect } from 'vitest';
-import type {
-  PipelineDefinition,
-  StageDefinition,
-  StageStatus,
-  AgentConfig,
-  ValidationResult,
-  ToolCallRequirements,
-  OutputContract,
-} from '../src/index.js';
-
-describe('contracts types', () => {
-  it('can create valid pipeline definition', () => {
-    const pipeline: PipelineDefinition = {
-      name: 'test-pipeline',
-      description: 'Test pipeline',
-      version: 1,
-      stages: [],
-    };
-    expect(pipeline.name).toBe('test-pipeline');
-  });
-
-  it('can create valid stage definition', () => {
-    const stage: StageDefinition = {
-      name: 'test-stage',
-      kind: 'analysis',
-      agent: 'test-agent',
-    };
-    expect(stage.kind).toBe('analysis');
-  });
-
-  it('status types are correct', () => {
-    const status: StageStatus = 'success';
-    expect(status).toBe('success');
-  });
-
-  it('can create agent config', () => {
-    const agent: AgentConfig = {
-      name: 'test-agent',
-      provider: 'openai',
-      model: 'gpt-4',
-    };
-    expect(agent.provider).toBe('openai');
-  });
-
-  it('can create pipeline with repo config', () => {
-    const pipeline: PipelineDefinition = {
-      name: 'test',
-      description: 'Test',
-      version: 1,
-      repo: {
-        url: 'https://github.com/test/repo',
-        branch: 'main',
-      },
-      stages: [],
-    };
-    expect(pipeline.repo?.url).toBe('https://github.com/test/repo');
-  });
-
-  it('validation result structure', () => {
-    const validation: ValidationResult = {
-      valid: true,
-      errors: [],
-      warnings: [],
-    };
-    expect(validation.valid).toBe(true);
-    expect(validation.errors).toEqual([]);
-  });
-
-  it('ToolCallRequirements supports required_tool_groups for OR semantics', () => {
-    const req: ToolCallRequirements = {
-      minimum: 1,
-      required_tools: ['repo_manager-read_file'],
-      required_tool_groups: [
-        ['repo_manager-write_file', 'repo_manager-apply_patch'],
-      ],
-    };
-    expect(req.required_tool_groups).toHaveLength(1);
-    expect(req.required_tool_groups![0]).toEqual([
-      'repo_manager-write_file',
-      'repo_manager-apply_patch',
-    ]);
-  });
-
-  it('OutputContract.tool_calls accepts required_tool_groups', () => {
-    const contract: OutputContract = {
-      name: 'code-generation',
-      version: 1,
-      tool_calls: {
-        minimum: 1,
-        required_tool_groups: [
-          ['repo_manager-write_file', 'repo_manager-apply_patch'],
-        ],
-      },
-    };
-    expect(contract.tool_calls?.required_tool_groups).toBeDefined();
-  });
-});