From a61193d0b0612c19cd5208e1b575917ae2e759fc Mon Sep 17 00:00:00 2001 From: SammyBytes Date: Tue, 17 Nov 2026 07:43:37 -0400 Subject: [PATCH 1/7] feat: implement Claude Code runner options and validation in agent strategy --- .../src/codegen/generators/generateAgent.ts | 49 ++++++ packages/compiler/src/codegen/index.test.ts | 52 +++++- packages/compiler/src/parser/index.test.ts | 57 +++++++ .../compiler/src/parser/parsers/parseAgent.ts | 56 ++++++- packages/runtime/src/engine/agentAction.ts | 20 ++- .../runtime/src/engine/agents/agentConfig.ts | 30 ++++ .../src/strategies/agent/agentStrategy.ts | 6 + .../strategies/agent/claudeStrategy.test.ts | 151 ++++++++++++++++++ .../src/strategies/agent/claudeStrategy.ts | 122 ++++++++++++++ packages/runtime/src/types.ts | 1 + 10 files changed, 541 insertions(+), 3 deletions(-) create mode 100644 packages/runtime/src/strategies/agent/claudeStrategy.test.ts create mode 100644 packages/runtime/src/strategies/agent/claudeStrategy.ts diff --git a/packages/compiler/src/codegen/generators/generateAgent.ts b/packages/compiler/src/codegen/generators/generateAgent.ts index 3e74603..9fd45cd 100644 --- a/packages/compiler/src/codegen/generators/generateAgent.ts +++ b/packages/compiler/src/codegen/generators/generateAgent.ts @@ -40,6 +40,21 @@ export function generateAgent( | number | undefined; + // Claude Code runner options. They are only emitted for local runners. + const permissionMode = getPropertyValue(props.get("permission_mode")) as + | string + | undefined; + const maxTurns = getPropertyValue(props.get("max_turns")) as + | number + | undefined; + const fallbackModelProp = props.get("fallback_model"); + const allowedToolsProp = props.get("allowed_tools"); + const disallowedToolsProp = props.get("disallowed_tools"); + const maxBudgetUsd = getPropertyValue(props.get("max_budget_usd")) as + | number + | undefined; + const bare = getPropertyValue(props.get("bare")) as boolean | undefined; + const configFields: string[] = [`name: ${JSON.stringify(agentNode.name)}`]; if (providerProp !== undefined) { @@ -76,6 +91,40 @@ export function generateAgent( if (modelProp !== undefined) { configFields.push(`model: ${formatStringOrEnv(modelProp.value)}`); } + + if (permissionMode !== undefined) { + configFields.push(`permissionMode: ${JSON.stringify(permissionMode)}`); + } + + if (maxTurns !== undefined) { + configFields.push(`maxTurns: ${maxTurns}`); + } + + if (fallbackModelProp !== undefined) { + configFields.push( + `fallbackModel: ${formatStringOrEnv(fallbackModelProp.value)}`, + ); + } + + if (allowedToolsProp !== undefined) { + configFields.push( + `allowedTools: ${formatStringOrEnv(allowedToolsProp.value)}`, + ); + } + + if (disallowedToolsProp !== undefined) { + configFields.push( + `disallowedTools: ${formatStringOrEnv(disallowedToolsProp.value)}`, + ); + } + + if (maxBudgetUsd !== undefined) { + configFields.push(`maxBudgetUsd: ${maxBudgetUsd}`); + } + + if (bare !== undefined) { + configFields.push(`bare: ${bare}`); + } } if (systemPromptProp !== undefined) { diff --git a/packages/compiler/src/codegen/index.test.ts b/packages/compiler/src/codegen/index.test.ts index 8580239..83274a4 100644 --- a/packages/compiler/src/codegen/index.test.ts +++ b/packages/compiler/src/codegen/index.test.ts @@ -466,4 +466,54 @@ test("should omit strictSchema when the provider does not enable it", () => { '{ name: "Compatible", protocol: "openai-compatible", baseUrl: "http://localhost:11434/v1" }', ); expect(output).toContain("maxTokens: 256, retries: 0"); -}); \ No newline at end of file +}); +test("should generate Claude Code runner options for a local agent", () => { + const code = ` + agent ClaudeReviewer { + runner: claude, + workspace: "./src", + model: "sonnet", + permission_mode: "acceptEdits", + max_turns: 4, + fallback_model: "haiku", + allowed_tools: "Read, Grep", + disallowed_tools: "Bash", + max_budget_usd: 2.5, + bare: true, + reasoning_effort: "high", + timeout: 30 + } + `; + + const ast = new Parser(tokenize(code)).parse(); + const output = generateCode(ast); + + expect(output).toContain( + '{ name: "ClaudeReviewer", runner: "claude", workspace: "./src", model: "sonnet", permissionMode: "acceptEdits", maxTurns: 4, fallbackModel: "haiku", allowedTools: "Read, Grep", disallowedTools: "Bash", maxBudgetUsd: 2.5, bare: true, reasoningEffort: "high", timeout: 30000 }', + ); +}); + +test("should not emit Claude Code runner options for provider agents", () => { + const code = ` + provider Groq { + protocol: "openai-compatible", + base_url: "https://api.groq.com/openai/v1", + api_key: "test" + } + + agent Reviewer { + provider: Groq, + model: "test-model", + permission_mode: "acceptEdits", + max_turns: 4, + bare: true + } + `; + + const ast = new Parser(tokenize(code)).parse(); + const output = generateCode(ast); + + expect(output).not.toContain("permissionMode"); + expect(output).not.toContain("maxTurns"); + expect(output).not.toContain("bare"); +}); diff --git a/packages/compiler/src/parser/index.test.ts b/packages/compiler/src/parser/index.test.ts index 6304cdd..cead5d9 100644 --- a/packages/compiler/src/parser/index.test.ts +++ b/packages/compiler/src/parser/index.test.ts @@ -770,3 +770,60 @@ test("reports the exact position of an edition directive that is not first", () /'edition' directive must appear only once at the top of the file \(line 2, column 1\)/, ); }); + +test("should parse a Claude Code runner agent with runner options", () => { + const code = ` + agent ClaudeReviewer { + runner: claude, + workspace: ".", + model: "sonnet", + permission_mode: "acceptEdits", + max_turns: 4, + fallback_model: "haiku", + allowed_tools: "Read, Grep", + disallowed_tools: "Bash", + max_budget_usd: 2.5, + bare: true + } + `; + + const ast = new Parser(tokenize(code)).parse(); + const agent = ast.body[0]; + expect(agent.type).toBe("AgentDeclaration"); + + if (agent.type === "AgentDeclaration") { + const props = new Map( + agent.properties.map((prop) => [prop.name, prop.value.value]), + ); + + expect(props.get("runner")).toBe("claude"); + expect(props.get("permission_mode")).toBe("acceptEdits"); + expect(props.get("max_turns")).toBe(4); + expect(props.get("fallback_model")).toBe("haiku"); + expect(props.get("allowed_tools")).toBe("Read, Grep"); + expect(props.get("disallowed_tools")).toBe("Bash"); + expect(props.get("max_budget_usd")).toBe(2.5); + expect(props.get("bare")).toBe(true); + } +}); + +test("rejects invalid Claude Code runner options", () => { + const invalidProperties = [ + `permission_mode: "root"`, + `max_turns: 0`, + `max_budget_usd: 0`, + `bare: "yes"`, + ]; + + for (const property of invalidProperties) { + const code = ` + agent ClaudeReviewer { + runner: claude, + workspace: ".", + ${property} + } + `; + + expect(() => new Parser(tokenize(code)).parse()).toThrow(); + } +}); diff --git a/packages/compiler/src/parser/parsers/parseAgent.ts b/packages/compiler/src/parser/parsers/parseAgent.ts index db0db57..7459c57 100644 --- a/packages/compiler/src/parser/parsers/parseAgent.ts +++ b/packages/compiler/src/parser/parsers/parseAgent.ts @@ -1,4 +1,9 @@ -import { AgentRunner, type AgentRunnerKind } from "@sam-lang/runtime"; +import { + AgentRunner, + CLAUDE_PERMISSION_MODES, + type AgentRunnerKind, + type ClaudePermissionMode, +} from "@sam-lang/runtime"; import type { AgentNode, AgentPropertyNode, AgentPropertyType } from "../ast"; import type { IParserContext } from "../types"; import type { Token } from "../../lexer/tokens"; @@ -21,6 +26,13 @@ const AGENT_PROPERTY_VALIDATORS: Record = { max_tokens: validatePositiveInteger, retries: validateNonNegativeInteger, reasoning_effort: validateReasoningEffort, + permission_mode: validatePermissionMode, + max_turns: validatePositiveInteger, + fallback_model: validateStringOrEnv, + allowed_tools: validateStringOrEnv, + disallowed_tools: validateStringOrEnv, + max_budget_usd: validatePositiveNumber, + bare: validateBoolean, }; export function parseAgent(context: IParserContext): AgentNode { @@ -243,6 +255,29 @@ function validatePositiveInteger( } } +function validatePositiveNumber( + value: AgentPropertyType, + token: Token, +): void { + if ( + value.type !== "NumberLiteral" || + !Number.isFinite(value.value) || + value.value <= 0 + ) { + throw new Error( + `ValidationError in agent '${token.value}' (line ${token.line}): Expected a positive number value.`, + ); + } +} + +function validateBoolean(value: AgentPropertyType, token: Token): void { + if (value.type !== "BooleanLiteral") { + throw new Error( + `ValidationError in agent '${token.value}' (line ${token.line}): Expected a boolean value.`, + ); + } +} + function validateNonNegativeInteger( value: AgentPropertyType, token: Token, @@ -277,6 +312,25 @@ function validateReasoningEffort( } } +function validatePermissionMode( + value: AgentPropertyType, + token: Token, +): void { + const isStringOrIdentifier = + value.type === "StringLiteral" || value.type === "Identifier"; + + if ( + !isStringOrIdentifier || + !CLAUDE_PERMISSION_MODES.includes( + String(value.value) as ClaudePermissionMode, + ) + ) { + throw new Error( + `ValidationError in agent '${token.value}' (line ${token.line}): Invalid 'permission_mode'. Expected one of: ${CLAUDE_PERMISSION_MODES.join(", ")}.`, + ); + } +} + function consumeAgentPropertyName(context: IParserContext): Token { const token = context.peek(); if (token.type === "IDENTIFIER" || token.type === "PROVIDER") { diff --git a/packages/runtime/src/engine/agentAction.ts b/packages/runtime/src/engine/agentAction.ts index 8bd32f1..86b2200 100644 --- a/packages/runtime/src/engine/agentAction.ts +++ b/packages/runtime/src/engine/agentAction.ts @@ -3,6 +3,7 @@ import type { AgentError } from "../errors"; import { err, ok } from "../result"; import type { Result } from "../result"; import type { IAgentStrategy } from "../strategies/agent/agentStrategy"; +import { ClaudeStrategy } from "../strategies/agent/claudeStrategy"; import { MockStrategy } from "../strategies/agent/mockStrategy"; import { OpenCodeStrategy } from "../strategies/agent/opencodeStrategy"; import type { AgentConfig, LocalAgentConfig } from "./agents/agentConfig"; @@ -27,6 +28,7 @@ export type Runtime = { const strategyRegistry = new Map([ ["mock", new MockStrategy()], ["opencode", new OpenCodeStrategy()], + ["claude", new ClaudeStrategy()], ]); const providerStrategyRegistry = new Map([ @@ -50,8 +52,24 @@ async function executeRunner( const binary = strategy.getBinaryName(); const args = strategy.buildArgs(agent, inputPrompt, schema); + const result = await agentExecute(agent, binary, args); - return agentExecute(agent, binary, args); + if (!result.ok || !strategy.extractOutput) { + return result; + } + + try { + return ok(strategy.extractOutput(result.value)); + } catch (error) { + return err({ + code: "EXECUTION_ERROR", + agentName: agent.name, + runner: agent.runner, + exitCode: 0, + stderr: error instanceof Error ? error.message : String(error), + message: `Agent '${agent.name}' produced an invalid runner response.`, + }); + } } async function executeAgent( diff --git a/packages/runtime/src/engine/agents/agentConfig.ts b/packages/runtime/src/engine/agents/agentConfig.ts index ad0ef47..fc0a6f2 100644 --- a/packages/runtime/src/engine/agents/agentConfig.ts +++ b/packages/runtime/src/engine/agents/agentConfig.ts @@ -1,5 +1,17 @@ import type { AgentRunnerKind, ProviderProtocolKind } from "../../types"; +export const CLAUDE_PERMISSION_MODES = [ + "default", + "acceptEdits", + "plan", + "auto", + "dontAsk", + "bypassPermissions", + "manual", +] as const; + +export type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number]; + export type LocalAgentConfig = { name: string; runner: AgentRunnerKind; @@ -7,6 +19,24 @@ export type LocalAgentConfig = { systemPrompt?: string; model?: string; timeout?: number; + temperature?: number; + maxTokens?: number; + retries?: number; + reasoningEffort?: "low" | "medium" | "high"; + /** Claude Code `--permission-mode`. */ + permissionMode?: ClaudePermissionMode; + /** Claude Code `--max-turns`. */ + maxTurns?: number; + /** Claude Code `--fallback-model`. */ + fallbackModel?: string; + /** Comma-separated Claude Code `--allowedTools` entries. */ + allowedTools?: string; + /** Comma-separated Claude Code `--disallowedTools` entries. */ + disallowedTools?: string; + /** Claude Code `--max-budget-usd`. */ + maxBudgetUsd?: number; + /** Claude Code `--bare`, which skips project/user config discovery. */ + bare?: boolean; }; export type ProviderAgentConfig = { diff --git a/packages/runtime/src/strategies/agent/agentStrategy.ts b/packages/runtime/src/strategies/agent/agentStrategy.ts index 0bbed9a..f9f1d60 100644 --- a/packages/runtime/src/strategies/agent/agentStrategy.ts +++ b/packages/runtime/src/strategies/agent/agentStrategy.ts @@ -18,4 +18,10 @@ export interface IAgentStrategy { * @returns The binary name as a string. */ getBinaryName(): string; + /** + * Optionally normalizes raw stdout before Sam parses it as JSON. Strategies + * that use an envelope output format (for example Claude Code's JSON mode) + * implement this to return the model's actual answer. + */ + extractOutput?(rawStdout: string): string; } diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.test.ts b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts new file mode 100644 index 0000000..01cd951 --- /dev/null +++ b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts @@ -0,0 +1,151 @@ +import { describe, expect, test } from "bun:test"; +import { z } from "zod"; +import type { LocalAgentConfig } from "../../engine/agents/agentConfig"; +import { ClaudeStrategy } from "./claudeStrategy"; + +const strategy = new ClaudeStrategy(); + +const agent: LocalAgentConfig = { + name: "ClaudeReviewer", + runner: "claude", + workspace: ".", + model: "sonnet", +}; + +const ReviewSchema = z.object({ + approved: z.boolean(), + risk_level: z.string(), +}); + +function argsFor( + overrides: Partial = {}, + schema?: z.ZodTypeAny, +): string[] { + return strategy.buildArgs( + { ...agent, ...overrides }, + "Review this change", + schema, + ); +} + +describe("ClaudeStrategy", () => { + test("uses the claude binary", () => { + expect(strategy.getBinaryName()).toBe("claude"); + }); + + test("runs in print mode with the model and without persisted sessions", () => { + const args = argsFor(); + + expect(args.slice(0, 4)).toEqual(["-p", "--model", "sonnet", "--no-session-persistence"]); + expect(args.at(-1)).toBe("Review this change"); + expect(args).not.toContain("--output-format"); + }); + + test("appends the system prompt and maps reasoning effort", () => { + const args = argsFor({ + systemPrompt: "Be terse.", + reasoningEffort: "high", + }); + + expect(args).toContain("--append-system-prompt"); + expect(args[args.indexOf("--append-system-prompt") + 1]).toBe("Be terse."); + expect(args[args.indexOf("--effort") + 1]).toBe("high"); + }); + + test("maps permission, turn, model fallback, tools, budget, and bare options", () => { + const args = argsFor({ + permissionMode: "acceptEdits", + maxTurns: 4, + fallbackModel: "haiku", + allowedTools: "Read, Grep", + disallowedTools: "Bash, Edit", + maxBudgetUsd: 2.5, + bare: true, + }); + + expect(args[args.indexOf("--permission-mode") + 1]).toBe("acceptEdits"); + expect(args[args.indexOf("--max-turns") + 1]).toBe("4"); + expect(args[args.indexOf("--fallback-model") + 1]).toBe("haiku"); + expect( + args.flatMap((arg, index) => + arg === "--allowedTools" ? [args[index + 1]] : [], + ), + ).toEqual(["Read", "Grep"]); + expect( + args.flatMap((arg, index) => + arg === "--disallowedTools" ? [args[index + 1]] : [], + ), + ).toEqual(["Bash", "Edit"]); + expect(args[args.indexOf("--max-budget-usd") + 1]).toBe("2.5"); + expect(args).toContain("--bare"); + }); + + test("requests structured output when a schema is provided", () => { + const args = argsFor({}, ReviewSchema); + + expect(args[args.indexOf("--output-format") + 1]).toBe("json"); + const schemaArg = args[args.indexOf("--json-schema") + 1]; + expect(schemaArg).toBeDefined(); + + const jsonSchema = JSON.parse(schemaArg!) as { + type: string; + properties: Record; + required: string[]; + }; + + expect(jsonSchema.type).toBe("object"); + expect(jsonSchema.properties).toHaveProperty("approved"); + expect(jsonSchema.properties).toHaveProperty("risk_level"); + expect(jsonSchema.required).toEqual(["approved", "risk_level"]); + }); +}); + +describe("ClaudeStrategy.extractOutput", () => { + test("returns structured_output as JSON", () => { + const output = strategy.extractOutput( + JSON.stringify({ + type: "result", + subtype: "success", + is_error: false, + structured_output: { approved: true, risk_level: "low" }, + }), + ); + + expect(JSON.parse(output)).toEqual({ + approved: true, + risk_level: "low", + }); + }); + + test("returns the result text for non-structured runs", () => { + const output = strategy.extractOutput( + JSON.stringify({ + type: "result", + subtype: "success", + is_error: false, + result: "plain answer", + }), + ); + + expect(output).toBe("plain answer"); + }); + + test("passes plain text through when the CLI is not in JSON mode", () => { + expect(strategy.extractOutput("plain text output")).toBe( + "plain text output", + ); + }); + + test("throws when Claude Code reports an error result", () => { + expect(() => + strategy.extractOutput( + JSON.stringify({ + type: "result", + subtype: "error_during_execution", + is_error: true, + result: "provider rejected the request", + }), + ), + ).toThrow(/provider rejected the request/); + }); +}); diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.ts b/packages/runtime/src/strategies/agent/claudeStrategy.ts new file mode 100644 index 0000000..773f945 --- /dev/null +++ b/packages/runtime/src/strategies/agent/claudeStrategy.ts @@ -0,0 +1,122 @@ +import { z } from "zod"; +import type { IAgentStrategy } from "./agentStrategy"; +import type { AgentConfig } from "../../engine/agents/agentConfig"; + +function splitList(value: string): string[] { + return value + .split(",") + .map((item) => item.trim()) + .filter(Boolean); +} + +/** + * Runs an agent with the Claude Code CLI in non-interactive print mode. + * + * The prompt is passed as a positional argument and the optional system prompt + * is appended to Claude Code's built-in system prompt, so tool guidance and + * safety instructions stay intact. When a schema is present, Sam asks Claude + * Code for structured output and extracts the validated object from the JSON + * result envelope. + */ +export class ClaudeStrategy implements IAgentStrategy { + getBinaryName(): string { + return "claude"; + } + + buildArgs( + agent: AgentConfig, + inputPrompt: string, + schema?: z.ZodTypeAny, + ): string[] { + const args = ["-p"]; + + if (agent.model) { + args.push("--model", agent.model); + } + + if (agent.systemPrompt) { + args.push("--append-system-prompt", agent.systemPrompt); + } + + if (agent.reasoningEffort) { + args.push("--effort", agent.reasoningEffort); + } + + if ("permissionMode" in agent && agent.permissionMode) { + args.push("--permission-mode", agent.permissionMode); + } + + if ("maxTurns" in agent && agent.maxTurns !== undefined) { + args.push("--max-turns", String(agent.maxTurns)); + } + + if ("fallbackModel" in agent && agent.fallbackModel) { + args.push("--fallback-model", agent.fallbackModel); + } + + if ("allowedTools" in agent && agent.allowedTools) { + for (const tool of splitList(agent.allowedTools)) { + args.push("--allowedTools", tool); + } + } + + if ("disallowedTools" in agent && agent.disallowedTools) { + for (const tool of splitList(agent.disallowedTools)) { + args.push("--disallowedTools", tool); + } + } + + if ("maxBudgetUsd" in agent && agent.maxBudgetUsd !== undefined) { + args.push("--max-budget-usd", String(agent.maxBudgetUsd)); + } + + if ("bare" in agent && agent.bare) { + args.push("--bare"); + } + + // Sam never resumes sessions, so do not leave transcripts behind. + args.push("--no-session-persistence"); + + if (schema) { + const jsonSchema = z.toJSONSchema(schema, { target: "draft-7" }); + args.push( + "--output-format", + "json", + "--json-schema", + JSON.stringify(jsonSchema), + ); + } + + args.push(inputPrompt); + return args; + } + + extractOutput(rawStdout: string): string { + const trimmed = rawStdout.trim(); + if (!trimmed) return trimmed; + + let parsed: unknown; + try { + parsed = JSON.parse(trimmed); + } catch { + return trimmed; + } + + if (!parsed || typeof parsed !== "object") return trimmed; + + const envelope = parsed as Record; + + if (envelope.structured_output !== undefined) { + return JSON.stringify(envelope.structured_output); + } + + if (typeof envelope.result === "string") { + if (envelope.is_error === true) { + throw new Error(`Claude Code reported an error: ${envelope.result}`); + } + return envelope.result.trim(); + } + + return trimmed; + } +} diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts index f3c33ef..fb66dd7 100644 --- a/packages/runtime/src/types.ts +++ b/packages/runtime/src/types.ts @@ -1,5 +1,6 @@ export const AgentRunner = { OPENCODE: "opencode", + CLAUDE: "claude", MOCK: "mock", } as const; From 9bba51e358772a1fabff1a763edbc16a0837b88a Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:13:45 -0400 Subject: [PATCH 2/7] fix(runner): only parse Claude Code JSON envelopes Always request --output-format json so the response shape is known, and only unwrap stdout when it is an envelope (type: "result"). Plain model replies that happen to look like JSON, such as {"result": "hola"}, are returned unchanged instead of being rewritten or treated as errors. Co-Authored-By: Claude Haiku 5.5 --- .../src/strategies/agent/claudeStrategy.test.ts | 14 ++++++++++++-- .../src/strategies/agent/claudeStrategy.ts | 15 +++++++++------ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.test.ts b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts index 01cd951..434d38d 100644 --- a/packages/runtime/src/strategies/agent/claudeStrategy.test.ts +++ b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts @@ -38,7 +38,8 @@ describe("ClaudeStrategy", () => { expect(args.slice(0, 4)).toEqual(["-p", "--model", "sonnet", "--no-session-persistence"]); expect(args.at(-1)).toBe("Review this change"); - expect(args).not.toContain("--output-format"); + expect(args[args.indexOf("--output-format") + 1]).toBe("json"); + expect(args).not.toContain("--json-schema"); }); test("appends the system prompt and maps reasoning effort", () => { @@ -130,12 +131,21 @@ describe("ClaudeStrategy.extractOutput", () => { expect(output).toBe("plain answer"); }); - test("passes plain text through when the CLI is not in JSON mode", () => { + test("passes plain text through unchanged", () => { expect(strategy.extractOutput("plain text output")).toBe( "plain text output", ); }); + test("does not treat a JSON-looking model reply as an envelope", () => { + expect(strategy.extractOutput('{"result":"hola"}')).toBe( + '{"result":"hola"}', + ); + expect( + strategy.extractOutput('{"result":"cuenta","is_error":true}'), + ).toBe('{"result":"cuenta","is_error":true}'); + }); + test("throws when Claude Code reports an error result", () => { expect(() => strategy.extractOutput( diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.ts b/packages/runtime/src/strategies/agent/claudeStrategy.ts index 773f945..c204678 100644 --- a/packages/runtime/src/strategies/agent/claudeStrategy.ts +++ b/packages/runtime/src/strategies/agent/claudeStrategy.ts @@ -77,14 +77,13 @@ export class ClaudeStrategy implements IAgentStrategy { // Sam never resumes sessions, so do not leave transcripts behind. args.push("--no-session-persistence"); + // Always request the JSON envelope so extractOutput never has to guess + // whether stdout is plain text or an envelope. + args.push("--output-format", "json"); + if (schema) { const jsonSchema = z.toJSONSchema(schema, { target: "draft-7" }); - args.push( - "--output-format", - "json", - "--json-schema", - JSON.stringify(jsonSchema), - ); + args.push("--json-schema", JSON.stringify(jsonSchema)); } args.push(inputPrompt); @@ -106,6 +105,10 @@ export class ClaudeStrategy implements IAgentStrategy { const envelope = parsed as Record; + // Only treat the output as an envelope when it is one. Plain text that + // happens to be JSON (for example {"result": "..."}) passes through. + if (envelope.type !== "result") return trimmed; + if (envelope.structured_output !== undefined) { return JSON.stringify(envelope.structured_output); } From 06e262cdf6eb7918357824ca2479c57b03744fa7 Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:13:45 -0400 Subject: [PATCH 3/7] feat(parser): reject provider-only options for the claude runner temperature, max_tokens and retries only take effect for HTTP providers. Process runners ignore them silently, so the parser now rejects them when runner is claude. timeout is kept: the process executor enforces it for every runner. Field docs in LocalAgentConfig describe where each applies. Co-Authored-By: Claude Haiku 5.5 --- packages/compiler/src/parser/index.test.ts | 28 +++++++++++++++++++ .../compiler/src/parser/parsers/parseAgent.ts | 27 ++++++++++++++++++ .../runtime/src/engine/agents/agentConfig.ts | 4 +++ 3 files changed, 59 insertions(+) diff --git a/packages/compiler/src/parser/index.test.ts b/packages/compiler/src/parser/index.test.ts index cead5d9..decfe97 100644 --- a/packages/compiler/src/parser/index.test.ts +++ b/packages/compiler/src/parser/index.test.ts @@ -827,3 +827,31 @@ test("rejects invalid Claude Code runner options", () => { expect(() => new Parser(tokenize(code)).parse()).toThrow(); } }); + +test("rejects provider-only options on the claude runner", () => { + for (const property of [`temperature: 0.2`, `max_tokens: 100`, `retries: 2`]) { + const code = ` + agent ClaudeReviewer { + runner: claude, + workspace: ".", + ${property} + } + `; + + expect(() => new Parser(tokenize(code)).parse()).toThrow( + /not supported by runner 'claude'/, + ); + } +}); + +test("accepts timeout on the claude runner", () => { + const code = ` + agent ClaudeReviewer { + runner: claude, + workspace: ".", + timeout: 60000 + } + `; + + expect(() => new Parser(tokenize(code)).parse()).not.toThrow(); +}); diff --git a/packages/compiler/src/parser/parsers/parseAgent.ts b/packages/compiler/src/parser/parsers/parseAgent.ts index 7459c57..64cb01f 100644 --- a/packages/compiler/src/parser/parsers/parseAgent.ts +++ b/packages/compiler/src/parser/parsers/parseAgent.ts @@ -143,6 +143,33 @@ function validateAgentProperties( validateExecutionTarget(agentToken, present); validatePromptExclusivity(agentToken, present); + validateClaudeRunnerProperties(agentToken, properties); +} + +// Properties that the claude runner cannot honor. Claude Code has no +// temperature, max-tokens or HTTP-style retry control, and Sam does not retry +// process runs, so accepting these would silently do nothing. +// `timeout` is not listed: the process executor enforces it for every runner. +const CLAUDE_UNSUPPORTED_PROPERTIES = new Set([ + "temperature", + "max_tokens", + "retries", +]); + +function validateClaudeRunnerProperties( + agentToken: Token, + properties: AgentPropertyNode[], +): void { + const runner = properties.find((prop) => prop.name === "runner"); + if (!runner || String(runner.value.value) !== AgentRunner.CLAUDE) return; + + for (const prop of properties) { + if (CLAUDE_UNSUPPORTED_PROPERTIES.has(prop.name)) { + throw new Error( + `ValidationError in agent '${agentToken.value}' (line ${agentToken.line}): '${prop.name}' is not supported by runner 'claude'. Remove it, or use a 'provider' for HTTP models.`, + ); + } + } } // --- Business logic validators for specific properties --- diff --git a/packages/runtime/src/engine/agents/agentConfig.ts b/packages/runtime/src/engine/agents/agentConfig.ts index fc0a6f2..4471711 100644 --- a/packages/runtime/src/engine/agents/agentConfig.ts +++ b/packages/runtime/src/engine/agents/agentConfig.ts @@ -18,9 +18,13 @@ export type LocalAgentConfig = { workspace: string; systemPrompt?: string; model?: string; + /** Milliseconds. Enforced for every runner (process and HTTP). */ timeout?: number; + /** HTTP providers only. The parser rejects it for the `claude` runner. */ temperature?: number; + /** HTTP providers only. The parser rejects it for the `claude` runner. */ maxTokens?: number; + /** HTTP providers only. The parser rejects it for the `claude` runner. */ retries?: number; reasoningEffort?: "low" | "medium" | "high"; /** Claude Code `--permission-mode`. */ From fc63a460c9b404601448a0f1078752aad97b3458 Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:13:45 -0400 Subject: [PATCH 4/7] fix(runner): run the native Claude binary on Windows The npm install puts claude.cmd first on PATH. Bun refuses to pass arguments with cmd special characters to .cmd files, and every structured call carries a JSON schema with those characters, so the run failed before Claude Code started. Resolve the claude.exe that the shim wraps when the PATH entry is a .cmd or .bat file. Other platforms and installs are unchanged. Co-Authored-By: Claude Haiku 5.5 --- .../strategies/agent/claudeStrategy.test.ts | 3 ++- .../src/strategies/agent/claudeStrategy.ts | 27 ++++++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.test.ts b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts index 434d38d..bffa40f 100644 --- a/packages/runtime/src/strategies/agent/claudeStrategy.test.ts +++ b/packages/runtime/src/strategies/agent/claudeStrategy.test.ts @@ -30,7 +30,8 @@ function argsFor( describe("ClaudeStrategy", () => { test("uses the claude binary", () => { - expect(strategy.getBinaryName()).toBe("claude"); + // May resolve to the native claude.exe on Windows (see resolveClaudeBinary). + expect(strategy.getBinaryName()).toMatch(/claude(\.exe)?$/); }); test("runs in print mode with the model and without persisted sessions", () => { diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.ts b/packages/runtime/src/strategies/agent/claudeStrategy.ts index c204678..e2ef052 100644 --- a/packages/runtime/src/strategies/agent/claudeStrategy.ts +++ b/packages/runtime/src/strategies/agent/claudeStrategy.ts @@ -1,3 +1,5 @@ +import { existsSync } from "node:fs"; +import { dirname, join } from "node:path"; import { z } from "zod"; import type { IAgentStrategy } from "./agentStrategy"; import type { AgentConfig } from "../../engine/agents/agentConfig"; @@ -9,6 +11,29 @@ function splitList(value: string): string[] { .filter(Boolean); } +/** + * On Windows, the npm install puts a `claude.cmd` shim first on PATH. Bun + * refuses to pass arguments containing cmd special characters to .cmd files, + * and the structured-output JSON schema always contains them. Run the native + * binary the shim wraps instead. + */ +function resolveClaudeBinary(): string { + if (process.platform !== "win32") return "claude"; + + const found = Bun.which("claude"); + if (!found || !/\.(cmd|bat)$/i.test(found)) return "claude"; + + const native = join( + dirname(found), + "node_modules", + "@anthropic-ai", + "claude-code", + "bin", + "claude.exe", + ); + return existsSync(native) ? native : "claude"; +} + /** * Runs an agent with the Claude Code CLI in non-interactive print mode. * @@ -20,7 +45,7 @@ function splitList(value: string): string[] { */ export class ClaudeStrategy implements IAgentStrategy { getBinaryName(): string { - return "claude"; + return resolveClaudeBinary(); } buildArgs( From eb18c3c6bf3bb02af20c14a8c8c447580998fdb4 Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:30:32 -0400 Subject: [PATCH 5/7] docs: add Claude runner follow-ups to the roadmap Link the RunnerPool, DSL timeout unit, and permissions issues, and record the measured per-call overhead of the claude runner. Co-Authored-By: Claude Haiku 5.5 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f21df8d..9ce9529 100644 --- a/README.md +++ b/README.md @@ -572,6 +572,7 @@ gh attestation verify sam-linux-x64 --repo SammyBytes/Sam * **v0.4.0 — Direct Execution** *(Done)*: `sam run` with positional arguments and stdin pipelines, smart entry point resolution, standalone compiled binaries for Linux/macOS/Windows, tag-driven releases, and guaranteed temporary-file cleanup. * **v0.5.0 — Providers** *(Done)*: top-level `provider` declarations, OpenAI-compatible HTTP execution, `env()` expansion, `strict_schema` structured outputs, native `retries` with `Retry-After` backoff, `max_tokens` limits, `reasoning_effort` budgets, and full backward compatibility with local `opencode` and `mock` runners. * **v0.6.0 — Integrations & Analyzer** *(Next)*: additional provider protocols, richer `model` configuration, webhook triggers, contract validation loops, a compiler-level `sam check` analyzer for best-practice warnings, and a repository-level technical whitepaper. +* **Claude Code runner hardening** *(Planned, v0.6.0)*: the `claude` runner (`runner: claude`, branch `feat/claude-code-runner`) is functional for structured and `use unsafe` calls on Windows, but needs three follow-ups tracked as issues: [#18](https://github.com/SammyBytes/Sam/issues/18) a `RunnerPool` that reuses and cleans up processes, [#19](https://github.com/SammyBytes/Sam/issues/19) explicit DSL timeout units, and [#20](https://github.com/SammyBytes/Sam/issues/20) an explicit permissions block for models, workspace writes and authentication. A small cost benchmark found about $0.08 of fixed overhead per separate `claude -p` call; batching six reviews into one call cost about one fifth of six separate calls, while `haiku` was not cheaper per call than `sonnet` in that run. * **v0.8.0 — Deeper Analysis** *(Planned)*: analyzer output as JSON, project-level rule configuration, inline suppressions (which require comment syntax in the lexer), an extensible model capability table, editor/CI integrations, and a website edition of the whitepaper maintained as the project's long-form history. Warnings stay non-blocking by default; `sam check --strict` promotes them to errors. * **v1.0.0 — Self-Hosting** *(Planned)*: a compiler written in Sam itself, retiring `@sam-lang/compiler` and removing the TypeScript bootstrap toolchain. From 141975f38229e6a1e835ef745b343ce6abe006a8 Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:46:56 -0400 Subject: [PATCH 6/7] docs: add sam-automation skill for writing and running .sb flows Project skill that teaches Claude to write, compile, dry-run and cost small Sam automations. Covers the verified syntax, timeout units, claude runner rules, measured per-call cost, parallelism via separate sam run processes, and known pitfalls. Co-Authored-By: Claude Haiku 5.5 --- .claude/skills/sam-automation/SKILL.md | 95 ++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 .claude/skills/sam-automation/SKILL.md diff --git a/.claude/skills/sam-automation/SKILL.md b/.claude/skills/sam-automation/SKILL.md new file mode 100644 index 0000000..e4a6d02 --- /dev/null +++ b/.claude/skills/sam-automation/SKILL.md @@ -0,0 +1,95 @@ +--- +name: sam-automation +description: Write, validate and run Sam (.sb) automations that delegate small, well-scoped tasks to LLM agents (claude, opencode, HTTP providers). Use when the user wants a .sb file, an agent pipeline, a scripted review or triage flow, or wants to split work across cheaper agents. +--- + +# Sam automation + +Sam is a declarative DSL. A `.sb` file declares **schemas** (expected output shapes), **agents** (who runs the work), and **flows** (the steps). Claude's job here is to write the `.sb`, check it, run it on a small input, and report what it cost. + +## Workflow + +1. **Scope the task.** Decide which steps need a model and which are plain logic. Model calls are the expensive part. +2. **Write the `.sb`** following the syntax below. Keep the file in the project, not in scratch. +3. **Compile** before anything else: `sam compile `. Fix every error first. +4. **Dry run** with `runner: mock` for the agents. The mock returns schema-shaped placeholder output, so the control flow can be checked without spending tokens. +5. **Real run** on one small input with `sam run --flow= ""`. Keep `max_budget_usd` low while testing. +6. **Report** what ran, the cost if known, and any error code (see Pitfalls). + +## Syntax + +Verified with `sam compile` against this repo. + +```sam +schema Verdict { + approved: boolean, + risk_level: string +} + +agent Reviewer { + runner: claude, + model: "sonnet", + workspace: "./src", + system_prompt: "Return only the requested JSON.", + permission_mode: "plan", + max_turns: 4, + max_budget_usd: 0.25, + disallowed_tools: "Bash, Edit, Write", + timeout: 120 +} + +flow Review(change: string) { + let verdict = use Reviewer(change) + if (!verdict.ok) { + return verdict + } + return verdict.value +} +``` + +- **Schemas:** fields are `string`, `number`, `boolean`, or `array` (untyped, so no element type or length is enforced). +- **Agents:** either `runner:` (local: `claude`, `opencode`, `mock`, which need `workspace`) or `provider:` (HTTP, which needs `model`). Not both. +- **`timeout` is in seconds** in `.sb` (`timeout: 60` means 60 s). The runtime converts it to milliseconds. Writing `timeout: 120000` means about 33 hours. +- **Calls:** `use Agent(input)` validates the output against the schema. `use unsafe Agent(input)` returns raw text and must not have ``. +- **Results:** every `use` returns `{ ok, value }` on success or `{ ok: false, ... }` with an error code. +- **Flows:** `let`, `if (...) { } else { }`, `return`, operators `==`, `!=`, `<`, `>`, `!`. Mark helpers `private flow`. +- **Strings:** double quotes, or backtick templates with `${expr}`. There is no `+` concatenation. +- **Not available:** loops, and `parallel(...)` (the token exists but the compiler rejects it with `Unexpected token 'parallel'`). + +## Claude runner rules + +- `temperature`, `max_tokens` and `retries` are **rejected** for `runner: claude`. They only apply to HTTP providers. +- Use `permission_mode: "plan"` and `disallowed_tools: "Bash, Edit, Write"` unless the task explicitly needs more. Workspace writes are not configurable yet (tracked in the permissions issue). +- Use `max_turns: 4` or more. `max_turns: 2` was too low for `sonnet` in plan mode, and the run failed with `error_max_turns`. +- Every `claude` call is a separate Claude Code session with fixed overhead. Measured at about $0.08 per call, before the task itself. + +## Cost rules (from measurements) + +- **Batch related items in one call when you can**, because the per-call overhead dominates small tasks. In the measured run, six reviews in one `sonnet` call cost about one fifth of six separate calls. The DSL cannot type a batch result, though, since `array` has no element type. Batching then means one schema per fixed item count, which is awkward. Say so to the user instead of hiding it. +- **Do not assume `haiku` is cheaper per call** on the `claude` runner. In the measured run it cost slightly more than `sonnet` per call, because each model builds its own cache. +- Set `max_budget_usd` on every agent. Report the total you expect to spend before a large run. + +## Parallel work + +There is no DSL `parallel`. To run several agents in parallel, launch separate `sam run` processes in the background, one per independent input, collect each JSON result, and merge them in the orchestrating step. Keep the number of concurrent processes small. Two concurrent runs with different models were verified. + +## Secrets and safety + +- Never write API keys into `.sb` files or commit them. Use `env("NAME")` for values such as the workspace path, and set variables in the shell or the CI environment. +- `ANTHROPIC_API_KEY`, when set, makes Claude Code bill per token through the API instead of the user's subscription. Set it only for the run that needs it, such as `bare` mode or unattended jobs. +- `bare: true` needs an API key, according to `claude --help`. + +## Pitfalls seen in testing + +- **Timeouts in milliseconds** silently become enormous. Use seconds. +- **`max_turns` too low** causes `error_max_turns` when the model wants a tool call first. +- **Child process failures** return the full JSON envelope in `stderr`. Read the `subtype` and `errors` fields instead of the whole blob. +- **Windows `.cmd` shims:** on Windows the npm install of `claude` is a `.cmd`. Sam resolves the native `claude.exe` behind it. If a structured call fails with `cmd.exe special character`, check the `claude` install. +- **Unknown model names** return `EXECUTION_ERROR` with `unrecognized_model`. +- **Missing workspace** looks like a missing binary. If a run fails with `ENOENT ... uv_spawn 'bun'` (or `'claude'`), first check that the agent's `workspace` path exists relative to where `sam run` is started. The binary is usually fine. + +## Done when + +- `sam compile` passes. +- A `mock` run shows the flow's control path. +- One real run on a small input returned `ok: true` with a value matching the schema, and the spend is reported. From d3b44c355e56e64c829ad6b74f3963151084a97a Mon Sep 17 00:00:00 2001 From: Sammy <43734971+SammyBytes@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:01:33 -0400 Subject: [PATCH 7/7] docs: add workflow examples for common Sam automations Three single-purpose flows: ticket readiness check, PR review gate, and iteration digest (use unsafe). Adds a parallel fan-out script that runs one flow over a folder of inputs as separate sam run processes. Inputs are synthetic or come from this public repository. Co-Authored-By: Claude Haiku 5.5 --- examples/workflows/README.md | 46 ++++++++++++++++++ .../inputs/diff_claude_envelope_fix.patch | 48 +++++++++++++++++++ examples/workflows/inputs/tasks.txt | 4 ++ .../inputs/tickets/ticket_complete.txt | 11 +++++ .../inputs/tickets/ticket_incomplete.txt | 3 ++ examples/workflows/iteration_digest.sb | 19 ++++++++ examples/workflows/pr_review_gate.sb | 28 +++++++++++ examples/workflows/run_parallel.sh | 40 ++++++++++++++++ examples/workflows/ticket_readiness.sb | 26 ++++++++++ 9 files changed, 225 insertions(+) create mode 100644 examples/workflows/README.md create mode 100644 examples/workflows/inputs/diff_claude_envelope_fix.patch create mode 100644 examples/workflows/inputs/tasks.txt create mode 100644 examples/workflows/inputs/tickets/ticket_complete.txt create mode 100644 examples/workflows/inputs/tickets/ticket_incomplete.txt create mode 100644 examples/workflows/iteration_digest.sb create mode 100644 examples/workflows/pr_review_gate.sb create mode 100644 examples/workflows/run_parallel.sh create mode 100644 examples/workflows/ticket_readiness.sb diff --git a/examples/workflows/README.md b/examples/workflows/README.md new file mode 100644 index 0000000..67c7d73 --- /dev/null +++ b/examples/workflows/README.md @@ -0,0 +1,46 @@ +# Sam workflow examples + +Small, single-purpose automations. Each `.sb` file does one job and returns a +structured result, so a person or a script can act on it without reading a +long model reply. + +| File | Job | Output | +|---|---|---| +| `ticket_readiness.sb` | Checks that a ticket has an objective, out-of-scope notes and validation steps | `{ has_objective, has_out_of_scope, has_validation, missing_sections }` | +| `pr_review_gate.sb` | Reviews a diff and blocks when it finds blocking issues | `"approved"` or `"blocked"` | +| `iteration_digest.sb` | Writes a short status digest from task lines (uses `use unsafe`, free text) | plain text | +| `run_parallel.sh` | Runs one flow over every file in a folder, in parallel | one JSON file per input | + +## Run one example + +```bash +sam compile examples/workflows/ticket_readiness.sb +sam run examples/workflows/ticket_readiness.sb --flow=CheckTicket "$(cat examples/workflows/inputs/tickets/ticket_incomplete.txt)" +``` + +`inputs/` contains synthetic tickets, a task list, and a diff of public code +from this repository. Nothing from a private tracker belongs in this folder. + +## Dry run without tokens + +Copy an example and change `runner: claude` to `runner: mock`. The mock runner +returns placeholder output that matches the schema, so you can check the flow +logic first. + +## Fan out over many tickets + +```bash +./examples/workflows/run_parallel.sh examples/workflows/ticket_readiness.sb CheckTicket examples/workflows/inputs/tickets out/readiness +``` + +Each ticket is a separate `sam run` process. A failure in one does not stop the +others, and the script exits non-zero if any run failed. Errors go to +`.err` next to each output. + +## Cost notes + +- Each `claude` call pays a fixed overhead of roughly $0.08 before the task + itself. Keep `max_budget_usd` set on every agent. +- `ticket_readiness` uses `haiku`. `pr_review_gate` uses `sonnet`, because a + wrong approval costs more than the extra tokens. +- The DSL has no `parallel(...)` yet. Use `run_parallel.sh` instead. diff --git a/examples/workflows/inputs/diff_claude_envelope_fix.patch b/examples/workflows/inputs/diff_claude_envelope_fix.patch new file mode 100644 index 0000000..07bfc7a --- /dev/null +++ b/examples/workflows/inputs/diff_claude_envelope_fix.patch @@ -0,0 +1,48 @@ +commit 9bba51e358772a1fabff1a763edbc16a0837b88a +Author: Sammy <43734971+SammyBytes@users.noreply.github.com> +Date: Tue Nov 17 09:13:45 2026 -0400 + + fix(runner): only parse Claude Code JSON envelopes + + Always request --output-format json so the response shape is known, and + only unwrap stdout when it is an envelope (type: "result"). Plain model + replies that happen to look like JSON, such as {"result": "hola"}, are + returned unchanged instead of being rewritten or treated as errors. + + Co-Authored-By: Claude Haiku 5.5 + +diff --git a/packages/runtime/src/strategies/agent/claudeStrategy.ts b/packages/runtime/src/strategies/agent/claudeStrategy.ts +index 773f945..c204678 100644 +--- a/packages/runtime/src/strategies/agent/claudeStrategy.ts ++++ b/packages/runtime/src/strategies/agent/claudeStrategy.ts +@@ -77,14 +77,13 @@ export class ClaudeStrategy implements IAgentStrategy { + // Sam never resumes sessions, so do not leave transcripts behind. + args.push("--no-session-persistence"); + ++ // Always request the JSON envelope so extractOutput never has to guess ++ // whether stdout is plain text or an envelope. ++ args.push("--output-format", "json"); ++ + if (schema) { + const jsonSchema = z.toJSONSchema(schema, { target: "draft-7" }); +- args.push( +- "--output-format", +- "json", +- "--json-schema", +- JSON.stringify(jsonSchema), +- ); ++ args.push("--json-schema", JSON.stringify(jsonSchema)); + } + + args.push(inputPrompt); +@@ -106,6 +105,10 @@ export class ClaudeStrategy implements IAgentStrategy { + + const envelope = parsed as Record; + ++ // Only treat the output as an envelope when it is one. Plain text that ++ // happens to be JSON (for example {"result": "..."}) passes through. ++ if (envelope.type !== "result") return trimmed; ++ + if (envelope.structured_output !== undefined) { + return JSON.stringify(envelope.structured_output); + } diff --git a/examples/workflows/inputs/tasks.txt b/examples/workflows/inputs/tasks.txt new file mode 100644 index 0000000..1e43cf5 --- /dev/null +++ b/examples/workflows/inputs/tasks.txt @@ -0,0 +1,4 @@ +Login redesign | done +Webhook retries | in progress +Export to CSV | blocked by legal review +Dark mode | to do diff --git a/examples/workflows/inputs/tickets/ticket_complete.txt b/examples/workflows/inputs/tickets/ticket_complete.txt new file mode 100644 index 0000000..329c6aa --- /dev/null +++ b/examples/workflows/inputs/tickets/ticket_complete.txt @@ -0,0 +1,11 @@ +Add retry with backoff to the webhook sender + +Objective: retry failed webhook deliveries with exponential backoff so transient 5xx responses stop dropping events. + +What to do: +- Add a retry policy with a maximum of 5 attempts and jittered backoff. +- Persist the attempt count so retries survive a restart. + +Out of scope: do not change the webhook payload format or the signing logic. + +How to validate: simulate 503 responses from a test endpoint and confirm delivery succeeds on the third attempt. diff --git a/examples/workflows/inputs/tickets/ticket_incomplete.txt b/examples/workflows/inputs/tickets/ticket_incomplete.txt new file mode 100644 index 0000000..cff7f88 --- /dev/null +++ b/examples/workflows/inputs/tickets/ticket_incomplete.txt @@ -0,0 +1,3 @@ +Login button does nothing on Safari + +Users report that clicking the login button in Safari 17 does nothing. Chrome works. diff --git a/examples/workflows/iteration_digest.sb b/examples/workflows/iteration_digest.sb new file mode 100644 index 0000000..bc02fa7 --- /dev/null +++ b/examples/workflows/iteration_digest.sb @@ -0,0 +1,19 @@ +agent DigestWriter { + runner: claude, + model: "haiku", + workspace: ".", + system_prompt: "You write short status digests for a development team. Use at most five sentences. Mention what is done, what is in progress, and what is blocked.", + permission_mode: "plan", + max_turns: 4, + max_budget_usd: 0.15, + disallowed_tools: "Bash, Edit, Write", + timeout: 120 +} + +flow Digest(tasks: string) { + let result = use unsafe DigestWriter(`Write a status digest for these tasks:\n\n${tasks}`) + if (!result.ok) { + return result + } + return result.value +} diff --git a/examples/workflows/pr_review_gate.sb b/examples/workflows/pr_review_gate.sb new file mode 100644 index 0000000..b664822 --- /dev/null +++ b/examples/workflows/pr_review_gate.sb @@ -0,0 +1,28 @@ +schema Review { + approved: boolean, + risk_level: string, + blocking_issues: string +} + +agent DiffReviewer { + runner: claude, + model: "sonnet", + workspace: ".", + system_prompt: "You review code diffs for correctness, security and missing tests. Answer only with the requested JSON. blocking_issues is a short list, or the word none. Approve only when there are no blocking issues.", + permission_mode: "plan", + max_turns: 4, + max_budget_usd: 0.25, + disallowed_tools: "Bash, Edit, Write", + timeout: 180 +} + +flow ReviewDiff(diff: string) { + let review = use DiffReviewer(`Review this diff:\n\n${diff}`) + if (!review.ok) { + return review + } + if (review.value.approved == false) { + return "blocked" + } + return "approved" +} diff --git a/examples/workflows/run_parallel.sh b/examples/workflows/run_parallel.sh new file mode 100644 index 0000000..bb06657 --- /dev/null +++ b/examples/workflows/run_parallel.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# Runs one Sam flow over every ticket file in a directory, in parallel. +# Each run is an independent `sam run` process, so one failure does not stop the others. +# +# Usage: run_parallel.sh +# Set SAM to override the command, for example: +# SAM="bun run packages/cli/src/cli.ts" ./run_parallel.sh ticket_readiness.sb CheckTicket inputs/tickets out/ +set -euo pipefail + +sb="$1" +flow="$2" +indir="$3" +outdir="$4" +SAM="${SAM:-sam}" + +mkdir -p "$outdir" +pids=() +names=() + +for f in "$indir"/*; do + [ -f "$f" ] || continue + name="$(basename "$f")" + name="${name%.*}" + $SAM run "$sb" --flow="$flow" "$(cat "$f")" > "$outdir/$name.json" 2> "$outdir/$name.err" & + pids+=($!) + names+=("$name") +done + +status=0 +for i in "${!pids[@]}"; do + if wait "${pids[$i]}"; then + echo "ok ${names[$i]}" + else + echo "FAIL ${names[$i]} (see $outdir/${names[$i]}.err)" + status=1 + fi +done + +echo "done: ${#pids[@]} runs, outputs in $outdir" +exit $status diff --git a/examples/workflows/ticket_readiness.sb b/examples/workflows/ticket_readiness.sb new file mode 100644 index 0000000..2a06041 --- /dev/null +++ b/examples/workflows/ticket_readiness.sb @@ -0,0 +1,26 @@ +schema Readiness { + has_objective: boolean, + has_out_of_scope: boolean, + has_validation: boolean, + missing_sections: string +} + +agent TicketChecker { + runner: claude, + model: "haiku", + workspace: ".", + system_prompt: "You check engineering tickets for completeness. Answer only with the requested JSON. missing_sections is a comma-separated list of missing items, or the word none.", + permission_mode: "plan", + max_turns: 4, + max_budget_usd: 0.15, + disallowed_tools: "Bash, Edit, Write", + timeout: 120 +} + +flow CheckTicket(ticket: string) { + let result = use TicketChecker(`Check this ticket:\n\n${ticket}`) + if (!result.ok) { + return result + } + return result.value +}