@wix/pathgrade 0.29.0

package/dist/sdk/managed-session.js

@@ -0,0 +1,110 @@
+import { createAgentSession } from '../types.js';
+import { createAgentEnvironment } from '../agents/registry.js';
+import { withAbortTimeout } from '../utils/timeout.js';
+import { buildModelAgentResultLogEntry } from './agent-result-log.js';
+import { planRuntimePolicies } from './runtime-policy.js';
+import { getVisibleAssistantMessage } from './visible-turn.js';
+import { createAskBus } from './ask-bus/bus.js';
+export function createManagedSession(deps) {
+    const { ws, agentName, timeoutSec, messages, log, model, conversationWindow, llm } = deps;
+    const agentTimeoutMs = timeoutSec * 1000;
+    const deadlineMs = Date.now() + agentTimeoutMs;
+    const label = `Agent (limit: ${timeoutSec}s)`;
+    const transport = deps.transport;
+    const agent = createAgentEnvironment(agentName, transport);
+    const runtimePolicies = planRuntimePolicies(agentName, transport);
+    const askBus = deps.askBus
+        ?? createAskBus({ askUserTimeoutMs: deps.askUserTimeoutMs ?? 30_000 });
+    const sessionOptions = {
+        ...(ws.mcpConfigPath ? { mcpConfigPath: ws.mcpConfigPath } : {}),
+        ...(model ? { model } : {}),
+        ...(conversationWindow !== undefined ? { conversationWindow } : {}),
+        ...(runtimePolicies.length > 0 ? { runtimePolicies } : {}),
+        ...(llm ? { llm } : {}),
+        askBus,
+        ...(transport !== undefined ? { transport } : {}),
+    };
+    let session = null;
+    let setupDone = false;
+    let currentSignal;
+    const runCommand = async (cmd) => {
+        const result = await ws.exec(cmd, { signal: currentSignal });
+        log.push({
+            type: 'command',
+            timestamp: new Date().toISOString(),
+            command: cmd,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            exitCode: result.exitCode,
+        });
+        return result;
+    };
+    const executeTurn = async (message) => {
+        const remaining = deadlineMs - Date.now();
+        if (remaining <= 0)
+            throw new Error(`${label} timed out`);
+        return withAbortTimeout(async (signal) => {
+            currentSignal = signal;
+            if (!session) {
+                // Run auth setup commands before first agent turn
+                if (!setupDone) {
+                    for (const cmd of ws.setupCommands) {
+                        await ws.exec(cmd);
+                    }
+                    setupDone = true;
+                }
+                // Carry the workspace's resolved env (from `prepareWorkspace
+                // → resolveCredentials`) into the runtime handle so drivers
+                // that auth through `Options.env` (notably the Claude SDK
+                // driver) can lift Anthropic keys out. Drivers that only
+                // need the workspace path keep using `getWorkspacePath`.
+                const runtime = {
+                    handle: ws.path,
+                    workspacePath: ws.path,
+                    env: ws.env,
+                };
+                session = await createAgentSession(agent, runtime, runCommand, sessionOptions);
+                return session.start({ message });
+            }
+            return session.reply({ message });
+        }, remaining, label);
+    };
+    return {
+        async send(message) {
+            const isFirst = messages.length === 0;
+            log.push({
+                type: isFirst ? 'agent_start' : 'user_reply',
+                timestamp: new Date().toISOString(),
+                instruction: message,
+            });
+            messages.push({ role: 'user', content: message });
+            const turnResult = await executeTurn(message);
+            const response = getVisibleAssistantMessage(turnResult);
+            log.push(buildModelAgentResultLogEntry({
+                timestamp: new Date().toISOString(),
+                turnResult,
+                assistantMessage: response,
+            }));
+            for (const toolEvent of turnResult.toolEvents) {
+                log.push({ type: 'tool_event', timestamp: new Date().toISOString(), tool_event: toolEvent });
+            }
+            messages.push({ role: 'agent', content: response });
+            if (turnResult.exitCode !== 0) {
+                if (turnResult.timedOut)
+                    throw new Error(`${label} timed out (agent killed)`);
+                throw new Error(`Agent exited with code ${turnResult.exitCode}`);
+            }
+            return response;
+        },
+        executeTurn,
+        remainingMs() {
+            return Math.max(0, deadlineMs - Date.now());
+        },
+        async dispose() {
+            if (!session)
+                return;
+            await session.dispose?.();
+        },
+        askBus,
+    };
+}

package/dist/sdk/persona.d.ts

@@ -0,0 +1,5 @@
+import type { LLMPort } from '../utils/llm-types.js';
+import type { Persona, PersonaConfig } from './types.js';
+export declare function createPersona(config: PersonaConfig & {
+    llm: LLMPort;
+}): Persona;

package/dist/sdk/persona.js

@@ -0,0 +1,33 @@
+import { createConversationWindow } from './conversation-window.js';
+export function createPersona(config) {
+    const llm = config.llm;
+    const window = config.conversationWindow !== false
+        ? createConversationWindow({ ...config.conversationWindow, model: config.model, llm })
+        : null;
+    return {
+        async reply(chat) {
+            const prompt = await buildPrompt(config, chat, window);
+            const response = await llm.call(prompt, { model: config.model });
+            return response.text.trim();
+        },
+    };
+}
+function formatMessages(messages) {
+    return messages
+        .map(m => `${m.role === 'user' ? 'User' : 'Agent'}: ${m.content}`)
+        .join('\n\n');
+}
+async function buildPrompt(config, chat, window) {
+    const sections = [];
+    sections.push(`## Persona\n${config.description}`);
+    if (config.facts.length > 0) {
+        const factsList = config.facts.map(f => `- ${f}`).join('\n');
+        sections.push(`## Facts\n${factsList}`);
+    }
+    const history = window
+        ? await window.getHistory(chat.messages)
+        : formatMessages(chat.messages);
+    sections.push(`## Conversation History\n${history}`);
+    sections.push('Reply in character as the persona described above. Respond to the agent\'s latest message naturally and concisely.');
+    return sections.join('\n\n');
+}

package/dist/sdk/reaction-loader.d.ts

@@ -0,0 +1,4 @@
+import type { AskUserOption, AskUserQuestion, AskUserReaction, Message, Reaction, TextReaction } from './types.js';
+export declare function loadReactionSnapshotMessages(snapshotPath: string): Promise<Message[]>;
+export declare function loadReactionsFromFile(filePath: string): Promise<Reaction[]>;
+export type { AskUserOption, AskUserQuestion, AskUserReaction, TextReaction };

package/dist/sdk/reaction-loader.js

@@ -0,0 +1,119 @@
+import fs from 'fs-extra';
+import * as path from 'path';
+import createJiti from 'jiti';
+function isMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (candidate.role === 'user' || candidate.role === 'agent') && typeof candidate.content === 'string';
+}
+function compilePattern(pattern, fieldName, source) {
+    try {
+        return new RegExp(pattern);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid ${fieldName} pattern in ${source}: ${detail}`);
+    }
+}
+function toTextReaction(value, source) {
+    if (!(value.when instanceof RegExp) && typeof value.when !== 'string') {
+        throw new Error(`Text reaction entry in ${source} must define a RegExp or string "when" pattern.`);
+    }
+    if (typeof value.reply !== 'string') {
+        throw new Error(`Text reaction entry in ${source} must define a string "reply".`);
+    }
+    if (value.unless !== undefined && !(value.unless instanceof RegExp) && typeof value.unless !== 'string') {
+        throw new Error(`Text reaction entry in ${source} must define a RegExp or string "unless" pattern when present.`);
+    }
+    if (value.once !== undefined && typeof value.once !== 'boolean') {
+        throw new Error(`Text reaction entry in ${source} must define a boolean "once" flag when present.`);
+    }
+    return {
+        when: value.when instanceof RegExp ? value.when : compilePattern(value.when, 'when', source),
+        ...(value.unless === undefined
+            ? {}
+            : {
+                unless: value.unless instanceof RegExp
+                    ? value.unless
+                    : compilePattern(value.unless, 'unless', source),
+            }),
+        reply: value.reply,
+        ...(value.once === undefined ? {} : { once: value.once }),
+    };
+}
+function toAskUserReaction(value, source) {
+    const whenAsked = value.whenAsked;
+    const answer = value.answer;
+    if (!(whenAsked instanceof RegExp) && typeof whenAsked !== 'string' && typeof whenAsked !== 'function') {
+        throw new Error(`Ask-user reaction entry in ${source} must define a RegExp, string, or function "whenAsked".`);
+    }
+    if (typeof answer !== 'string' && !Array.isArray(answer) && typeof answer !== 'function') {
+        throw new Error(`Ask-user reaction entry in ${source} must define a string, string[], or function "answer".`);
+    }
+    if (Array.isArray(answer) && !answer.every((x) => typeof x === 'string')) {
+        throw new Error(`Ask-user reaction entry in ${source} "answer" array must contain only strings.`);
+    }
+    if (value.once !== undefined && typeof value.once !== 'boolean') {
+        throw new Error(`Ask-user reaction entry in ${source} must define a boolean "once" flag when present.`);
+    }
+    const compiledWhenAsked = whenAsked instanceof RegExp
+        ? whenAsked
+        : typeof whenAsked === 'function'
+            ? whenAsked
+            : compilePattern(whenAsked, 'whenAsked', source);
+    return {
+        whenAsked: compiledWhenAsked,
+        answer: answer,
+        ...(value.once === undefined ? {} : { once: value.once }),
+    };
+}
+function toReaction(value, source) {
+    if (!value || typeof value !== 'object') {
+        throw new Error(`Reaction entry in ${source} must be an object.`);
+    }
+    const reaction = value;
+    const hasWhen = reaction.when !== undefined;
+    const hasWhenAsked = reaction.whenAsked !== undefined;
+    if (hasWhen && hasWhenAsked) {
+        throw new Error(`Reaction entry in ${source} must not define both "when" and "whenAsked".`);
+    }
+    if (hasWhenAsked) {
+        return toAskUserReaction(reaction, source);
+    }
+    return toTextReaction(reaction, source);
+}
+function extractReactionList(moduleExports, source) {
+    if (Array.isArray(moduleExports))
+        return moduleExports;
+    if (moduleExports && typeof moduleExports === 'object') {
+        const record = moduleExports;
+        if (Array.isArray(record.default))
+            return record.default;
+        if (Array.isArray(record.reactions))
+            return record.reactions;
+    }
+    throw new Error(`Reaction file ${source} must export an array directly, as a default export, or as a named "reactions" export.`);
+}
+export async function loadReactionSnapshotMessages(snapshotPath) {
+    const resolvedPath = path.resolve(snapshotPath);
+    const snapshot = await fs.readJson(resolvedPath);
+    if (!Array.isArray(snapshot.messages) || !snapshot.messages.every(isMessage)) {
+        throw new Error(`Snapshot ${resolvedPath} must contain a valid messages array.`);
+    }
+    return snapshot.messages;
+}
+export async function loadReactionsFromFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    const extension = path.extname(resolvedPath).toLowerCase();
+    if (extension === '.json') {
+        const json = await fs.readJson(resolvedPath);
+        if (!Array.isArray(json)) {
+            throw new Error(`Reaction JSON ${resolvedPath} must contain an array.`);
+        }
+        return json.map((entry, index) => toReaction(entry, `${resolvedPath}#${index}`));
+    }
+    const jiti = createJiti(__filename, { moduleCache: false, interopDefault: false });
+    const loaded = jiti(resolvedPath);
+    return extractReactionList(loaded, resolvedPath).map((entry, index) => toReaction(entry, `${resolvedPath}#${index}`));
+}

package/dist/sdk/reaction-preview.d.ts

@@ -0,0 +1,6 @@
+import type { AskUserReaction, Message, Reaction, ReactionPreviewEntry, ReactionPreviewResult, TextReaction } from './types.js';
+export declare function isAskUserReaction(reaction: Reaction): reaction is AskUserReaction;
+export declare function isTextReaction(reaction: Reaction): reaction is TextReaction;
+export declare function inspectReactions(agentMessage: string, reactions: Reaction[], firedOnce: Set<number>): ReactionPreviewEntry[];
+export declare function pickReactionReply(agentMessage: string, reactions: Reaction[], firedOnce: Set<number>): string | null;
+export declare function previewReactions(messages: Message[], reactions: Reaction[]): ReactionPreviewResult;

package/dist/sdk/reaction-preview.js

@@ -0,0 +1,94 @@
+function testRegExp(pattern, input) {
+    const previousLastIndex = pattern.lastIndex;
+    try {
+        pattern.lastIndex = 0;
+        return pattern.test(input);
+    }
+    finally {
+        pattern.lastIndex = previousLastIndex;
+    }
+}
+function testUnless(pattern, input) {
+    if (!pattern)
+        return false;
+    try {
+        return testRegExp(pattern, input);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        console.warn(`Reaction unless check failed: ${detail}`);
+        return false;
+    }
+}
+export function isAskUserReaction(reaction) {
+    return 'whenAsked' in reaction;
+}
+export function isTextReaction(reaction) {
+    return 'when' in reaction;
+}
+export function inspectReactions(agentMessage, reactions, firedOnce) {
+    let firedThisTurn = false;
+    return reactions.map((reaction, reactionIndex) => {
+        if (isAskUserReaction(reaction)) {
+            // Ask-user reactions are never evaluated against assistant free text.
+            // They fire only on structured ask_user handshake turns (consumer in slice #4/#6).
+            return {
+                kind: 'ask_user',
+                reactionIndex,
+                whenAskedMatched: false,
+                fired: false,
+                status: 'no-match',
+            };
+        }
+        if (reaction.once && firedOnce.has(reactionIndex)) {
+            return {
+                kind: 'text',
+                reactionIndex,
+                whenMatched: false,
+                unlessMatched: false,
+                fired: false,
+                status: 'no-match',
+            };
+        }
+        const whenMatched = testRegExp(reaction.when, agentMessage);
+        const unlessMatched = whenMatched ? testUnless(reaction.unless, agentMessage) : false;
+        const eligible = whenMatched && !unlessMatched;
+        const fired = eligible && !firedThisTurn;
+        if (fired && reaction.once) {
+            firedOnce.add(reactionIndex);
+        }
+        if (fired) {
+            firedThisTurn = true;
+        }
+        return {
+            kind: 'text',
+            reactionIndex,
+            whenMatched,
+            unlessMatched,
+            fired,
+            status: fired ? 'fired' : (unlessMatched ? 'vetoed' : 'no-match'),
+            ...(fired ? { reply: reaction.reply } : {}),
+        };
+    });
+}
+export function pickReactionReply(agentMessage, reactions, firedOnce) {
+    const evaluations = inspectReactions(agentMessage, reactions, firedOnce);
+    const match = evaluations.find((evaluation) => evaluation.fired && evaluation.kind === 'text');
+    return match && match.kind === 'text' ? match.reply ?? null : null;
+}
+export function previewReactions(messages, reactions) {
+    const firedOnce = new Set();
+    const turns = [];
+    let turn = 0;
+    for (const message of messages) {
+        if (message.role !== 'agent')
+            continue;
+        turn++;
+        turns.push({
+            turn,
+            agentMessage: message.content,
+            reactions: inspectReactions(message.content, reactions, firedOnce),
+        });
+    }
+    return { turns };
+}

package/dist/sdk/run-scorer.d.ts

@@ -0,0 +1,10 @@
+import type { LLMPort } from '../utils/llm-types.js';
+import type { CheckScorer, Scorer, ScoreScorer, ScorerContext, ScorerResultEntry, ToolUsageScorer } from './types.js';
+export interface RunScorerOptions {
+    /** Required for `judge` scorers; ignored for other types. */
+    llm?: LLMPort;
+}
+export declare function runScorer(scorer: Scorer, ctx: ScorerContext, opts?: RunScorerOptions): Promise<ScorerResultEntry>;
+export declare function runCheckScorer(scorer: CheckScorer, ctx: ScorerContext): Promise<ScorerResultEntry>;
+export declare function runScoreScorer(scorer: ScoreScorer, ctx: ScorerContext): Promise<ScorerResultEntry>;
+export declare function runToolUsageScorer(scorer: ToolUsageScorer, ctx: ScorerContext): Promise<ScorerResultEntry>;

package/dist/sdk/run-scorer.js

@@ -0,0 +1,124 @@
+import { runJudgePipeline } from './judge-pipeline.js';
+import { runJudgeSession } from './judge-tool-session.js';
+import { clamp, makeErroredResult, matchesExpectation } from './scorer-utils.js';
+export async function runScorer(scorer, ctx, opts = {}) {
+    switch (scorer.type) {
+        case 'check':
+            return runCheckScorer(scorer, ctx);
+        case 'score':
+            return runScoreScorer(scorer, ctx);
+        case 'tool_usage':
+            return runToolUsageScorer(scorer, ctx);
+        case 'judge': {
+            if (!opts.llm) {
+                throw new Error('runScorer() requires opts.llm for judge scorers. Pass an LLM provider: runScorer(scorer, ctx, { llm: anthropicProvider })');
+            }
+            if (scorer.tools && scorer.tools.length > 0) {
+                const outcome = await runJudgeSession({ scorer, ctx, llm: opts.llm }, { emitLogs: false });
+                return buildEntryFromOutcome(scorer, outcome);
+            }
+            const [entry] = await runJudgePipeline(scorer, ctx, { llm: opts.llm });
+            return entry;
+        }
+    }
+}
+function buildEntryFromOutcome(scorer, outcome) {
+    if (outcome.code === null) {
+        return {
+            name: scorer.name,
+            type: 'judge',
+            score: outcome.score,
+            weight: scorer.weight,
+            details: outcome.details,
+            status: 'ok',
+        };
+    }
+    return {
+        name: scorer.name,
+        type: 'judge',
+        score: 0,
+        weight: scorer.weight,
+        details: outcome.details,
+        status: 'error',
+        errorCode: outcome.code,
+    };
+}
+export async function runCheckScorer(scorer, ctx) {
+    try {
+        const passed = await scorer.fn(ctx);
+        return {
+            name: scorer.name,
+            type: 'check',
+            score: passed ? 1.0 : 0.0,
+            weight: scorer.weight,
+            details: passed ? 'passed' : 'failed',
+            status: 'ok',
+        };
+    }
+    catch (error) {
+        return makeErroredResult('check', scorer.name, scorer.weight, error);
+    }
+}
+export async function runScoreScorer(scorer, ctx) {
+    try {
+        const raw = await scorer.fn(ctx);
+        if (typeof raw === 'number') {
+            return {
+                name: scorer.name,
+                type: 'score',
+                score: clamp(raw),
+                weight: scorer.weight,
+                status: 'ok',
+            };
+        }
+        return {
+            name: scorer.name,
+            type: 'score',
+            score: clamp(raw.score),
+            weight: scorer.weight,
+            details: raw.details,
+            status: 'ok',
+        };
+    }
+    catch (error) {
+        return makeErroredResult('score', scorer.name, scorer.weight, error);
+    }
+}
+export async function runToolUsageScorer(scorer, ctx) {
+    try {
+        const toolEvents = ctx.toolEvents;
+        if (toolEvents.length === 0) {
+            return {
+                name: scorer.name,
+                type: 'tool_usage',
+                score: 0,
+                weight: scorer.weight,
+                details: 'No tool events captured',
+                status: 'ok',
+            };
+        }
+        const checks = scorer.expectations.map((expectation) => {
+            const matches = toolEvents.filter((event) => matchesExpectation(event, expectation));
+            const passed = matches.length >= (expectation.min ?? 1)
+                && (expectation.max === undefined || matches.length <= expectation.max);
+            return {
+                passed,
+                weight: expectation.weight ?? 1,
+            };
+        });
+        const totalWeight = checks.reduce((sum, c) => sum + c.weight, 0);
+        const earnedWeight = checks.filter((c) => c.passed).reduce((sum, c) => sum + c.weight, 0);
+        const score = totalWeight === 0 ? 0 : earnedWeight / totalWeight;
+        return {
+            name: scorer.name,
+            type: 'tool_usage',
+            score,
+            weight: scorer.weight,
+            details: `${earnedWeight}/${totalWeight} expectation weight passed`,
+            status: 'ok',
+        };
+    }
+    catch (error) {
+        return makeErroredResult('tool_usage', scorer.name, scorer.weight, error);
+    }
+}

package/dist/sdk/runtime-policy.d.ts

@@ -0,0 +1,21 @@
+import type { AgentName, AgentTransport } from './types.js';
+import type { AgentTurnResult, LogEntry } from '../types.js';
+export interface RuntimePolicyDescriptor {
+    id: string;
+    version: string;
+}
+export interface RuntimePolicyRenderContext {
+    agent: AgentName;
+}
+export interface RuntimePolicyAuditEntry {
+    id: string;
+    version: string;
+    turns: number[];
+}
+export declare const NONINTERACTIVE_RUNTIME_POLICY: RuntimePolicyDescriptor;
+export declare function planRuntimePolicies(agent: AgentName, transport?: AgentTransport): RuntimePolicyDescriptor[];
+export declare function renderRuntimePolicy(policy: RuntimePolicyDescriptor, context: RuntimePolicyRenderContext): string;
+export declare function renderRuntimePolicies(policies: RuntimePolicyDescriptor[], context: RuntimePolicyRenderContext): string;
+export declare function prependRuntimePolicies(instruction: string, policies: RuntimePolicyDescriptor[], context: RuntimePolicyRenderContext): string;
+export declare function getRuntimePolicyLogMetadata(turnResult: AgentTurnResult): Record<string, unknown>;
+export declare function extractRuntimePolicyAuditEntries(log: LogEntry[]): RuntimePolicyAuditEntry[];

package/dist/sdk/runtime-policy.js

@@ -0,0 +1,89 @@
+import { getAgentCapabilities } from './types.js';
+export const NONINTERACTIVE_RUNTIME_POLICY = {
+    id: 'noninteractive-user-question',
+    version: '1',
+};
+const INTERACTIVE_TOOL_NAMES = {
+    claude: 'AskUserQuestion',
+    codex: 'request_user_input',
+    cursor: 'AskQuestion',
+};
+export function planRuntimePolicies(agent, transport) {
+    const capabilities = getAgentCapabilities(agent, transport);
+    if (!capabilities) {
+        return [];
+    }
+    return capabilities.interactiveQuestionTransport === 'noninteractive'
+        ? [NONINTERACTIVE_RUNTIME_POLICY]
+        : [];
+}
+export function renderRuntimePolicy(policy, context) {
+    if (policy.id !== NONINTERACTIVE_RUNTIME_POLICY.id) {
+        return '';
+    }
+    const toolName = INTERACTIVE_TOOL_NAMES[context.agent];
+    return [
+        'Runtime policy: non-interactive approval checkpoints',
+        `If the structured user-question tool ${toolName} cannot execute, treat that event as a blocked checkpoint.`,
+        'You must not retry the same checkpoint with paraphrases or formatting variants.',
+        'You must not infer approval or rejection from earlier user intent.',
+        'You must not continue past the blocked checkpoint.',
+        'Ask only the earliest outstanding approval checkpoint.',
+    ].join('\n');
+}
+export function renderRuntimePolicies(policies, context) {
+    return policies
+        .map((policy) => renderRuntimePolicy(policy, context))
+        .filter((policy) => policy.length > 0)
+        .join('\n\n');
+}
+export function prependRuntimePolicies(instruction, policies, context) {
+    const rendered = renderRuntimePolicies(policies, context);
+    if (!rendered) {
+        return instruction;
+    }
+    // Claude slash commands only activate when the first line still starts with `/command`.
+    // Preserve that first line, then inject runtime policy guidance immediately after it.
+    if (instruction.startsWith('/')) {
+        const newlineIndex = instruction.indexOf('\n');
+        if (newlineIndex === -1) {
+            return `${instruction}\n\n${rendered}`;
+        }
+        const firstLine = instruction.slice(0, newlineIndex);
+        const remainder = instruction.slice(newlineIndex + 1);
+        return `${firstLine}\n\n${rendered}\n${remainder}`;
+    }
+    return `${rendered}\n\n${instruction}`;
+}
+export function getRuntimePolicyLogMetadata(turnResult) {
+    return turnResult.runtimePoliciesApplied && turnResult.runtimePoliciesApplied.length > 0
+        ? { runtime_policies_applied: turnResult.runtimePoliciesApplied }
+        : {};
+}
+export function extractRuntimePolicyAuditEntries(log) {
+    const policies = new Map();
+    for (const entry of log) {
+        if (entry.type !== 'agent_result' || !entry.runtime_policies_applied || entry.runtime_policies_applied.length === 0) {
+            continue;
+        }
+        for (const policy of entry.runtime_policies_applied) {
+            const key = `${policy.id}@${policy.version}`;
+            const existing = policies.get(key);
+            if (!existing) {
+                policies.set(key, {
+                    id: policy.id,
+                    version: policy.version,
+                    turns: typeof entry.turn_number === 'number' ? [entry.turn_number] : [],
+                });
+                continue;
+            }
+            if (typeof entry.turn_number === 'number' && !existing.turns.includes(entry.turn_number)) {
+                existing.turns.push(entry.turn_number);
+            }
+        }
+    }
+    return [...policies.values()].map((policy) => ({
+        ...policy,
+        turns: [...policy.turns].sort((a, b) => a - b),
+    }));
+}

package/dist/sdk/scorer-utils.d.ts

@@ -0,0 +1,6 @@
+import type { ToolEvent } from '../tool-events.js';
+import type { ScorerResultEntry, ToolExpectation } from './types.js';
+export declare function clamp(n: number): number;
+export declare function getErrorMessage(error: unknown): string;
+export declare function matchesExpectation(event: ToolEvent, expectation: ToolExpectation): boolean;
+export declare function makeErroredResult(type: ScorerResultEntry['type'], name: string, weight: number, error: unknown): ScorerResultEntry;

package/dist/sdk/scorer-utils.js

@@ -0,0 +1,39 @@
+export function clamp(n) {
+    return Math.max(0, Math.min(1, n));
+}
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export function matchesExpectation(event, expectation) {
+    if (event.action !== expectation.action)
+        return false;
+    if (expectation.toolName && event.providerToolName !== expectation.toolName)
+        return false;
+    if (expectation.path && event.arguments?.path !== expectation.path)
+        return false;
+    if (expectation.commandContains) {
+        const cmd = String(event.arguments?.cmd || event.arguments?.command || '');
+        if (!cmd.includes(expectation.commandContains))
+            return false;
+    }
+    if (expectation.argumentPattern) {
+        const re = new RegExp(expectation.argumentPattern);
+        const values = Object.values(event.arguments || {}).filter((v) => typeof v === 'string');
+        if (!values.some((v) => re.test(v)))
+            return false;
+    }
+    return true;
+}
+export function makeErroredResult(type, name, weight, error) {
+    return {
+        name,
+        type,
+        score: 0,
+        weight,
+        details: getErrorMessage(error),
+        status: 'error',
+    };
+}