@opensearch-project/agent-health 0.3.0 → 0.5.2

package/lib/dist/lib/workflow/stepB.js

@@ -0,0 +1,99 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { spansToTrajectory, scanSessionSignals } from '../../services/traces/spansToTrajectory.js';
+/**
+ * Profile a session from its spans — deterministic, reuses #267 primitives.
+ * Pass `spans` directly (unit-testable) or resolve them via a seam upstream.
+ */
+export function profileSpans(sessionId, spans, opts = {}) {
+    const trajectory = spansToTrajectory(spans, opts.serviceName);
+    const signals = scanSessionSignals(spans, opts.serviceName);
+    const traceIds = [...new Set(spans.map((s) => s.traceId).filter(Boolean))];
+    return {
+        sessionId,
+        serviceName: opts.serviceName,
+        trajectory,
+        signals,
+        evaluator: opts.evaluator,
+        traceIds,
+    };
+}
+/**
+ * Build the reasoner prompt from profiles + the cumulative ledger. Pure, so the
+ * exact instruction surface is unit-testable and reviewable.
+ */
+export function buildAgentEditsPrompt(profiles, opts = {}) {
+    const rubric = profiles.find((p) => p.evaluator?.systemPrompt)?.evaluator?.systemPrompt;
+    const ledger = opts.ledger?.render();
+    const signalLines = profiles.flatMap((p) => p.signals.map((s) => `  - [${s.severity}] ${p.sessionId}: ${s.title}`));
+    return [
+        `You are improving the agent in its OWN repo${opts.repo ? ` (${opts.repo})` : ''}.`,
+        '',
+        rubric ? `## Rubric (evaluator)\n${rubric}` : '',
+        '',
+        ledger ? `${ledger}\n(Weight this human feedback ABOVE the signals.)` : '',
+        '',
+        '## Deterministic signals observed across the profiled sessions',
+        signalLines.length ? signalLines.join('\n') : '  (none)',
+        '',
+        '## Task',
+        'Propose concrete, minimal, generalizable edits. Return ONLY a JSON array:',
+        '[{ "file": "...", "change": "...", "why": "<tie to a signal/rubric/feedback + cite session ids>", "priority": "high|medium|low", "evidence": ["sessionId/traceId"] }]',
+    ]
+        .filter((l) => l !== '')
+        .join('\n');
+}
+/** Default reasoner: spawn `claude -p <prompt>` and return stdout. */
+export const defaultReason = async (prompt) => {
+    const { spawn } = await import('child_process');
+    return await new Promise((resolve, reject) => {
+        const child = spawn('claude', ['-p', prompt, '--model', 'sonnet'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (d) => (out += d.toString()));
+        child.stderr.on('data', (d) => (err += d.toString()));
+        child.on('error', reject);
+        child.on('close', (code) => (code === 0 ? resolve(out) : reject(new Error(`claude exited ${code}: ${err}`))));
+    });
+};
+/** Parse the reasoner output into AgentEdits (tolerant of fenced JSON). */
+export function parseAgentEdits(raw) {
+    const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const body = fenced ? fenced[1] : raw;
+    const start = body.indexOf('[');
+    const end = body.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return [];
+    try {
+        const arr = JSON.parse(body.slice(start, end + 1));
+        if (!Array.isArray(arr))
+            return [];
+        return arr
+            .filter((e) => e && typeof e.file === 'string' && typeof e.change === 'string')
+            .map((e) => ({
+            file: e.file,
+            change: e.change,
+            why: e.why ?? '',
+            priority: ((p) => (p === 'high' || p === 'low' ? p : 'medium'))(String(e.priority ?? '').toLowerCase()),
+            evidence: Array.isArray(e.evidence) ? e.evidence : undefined,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Derive concrete agent-repo edits from session profiles + the cumulative
+ * ledger. `reason` is injectable (defaults to `claude -p`).
+ */
+export async function deriveAgentEdits(profiles, opts = {}) {
+    if (profiles.length === 0)
+        return [];
+    const prompt = buildAgentEditsPrompt(profiles, { repo: opts.repo, ledger: opts.ledger });
+    const reason = opts.reason ?? defaultReason;
+    const raw = await reason(prompt);
+    return parseAgentEdits(raw);
+}
+//# sourceMappingURL=stepB.js.map

package/lib/dist/lib/workflow/stepB.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepB.js","sourceRoot":"","sources":["../../../workflow/stepB.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/workflow/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Workflow SDK — shared types.
+ *
+ * A workflow is a deterministic series of steps with two stochastic nodes
+ * (the agent calls). Sources, the feedback ledger, staging and consolidation
+ * are all deterministic plumbing around those calls. See lib/workflow/workflow.ts.
+ */
+import type { TrajectoryStep } from '../../types/index.js';
+import type { FeedbackLedger } from './ledger.js';
+/** A unit of work. Duck-typed — a source returns plain objects of this shape. */
+export interface WorkItem {
+    /** Stable dedup key (ticket id, page id, email msg-id). */
+    id: string;
+    /** What the agent receives (a ticket URL or body). */
+    prompt: string;
+    /** Free-form provenance the sink can use (cti, severity, raw payload). */
+    meta?: Record<string, unknown>;
+}
+/** A source is just an async function returning WorkItems — no interface to implement. */
+export type SourceFetchFn = (args: {
+    since?: string;
+}) => Promise<WorkItem[]> | WorkItem[];
+export interface SourceHandle {
+    readonly name: string;
+    readonly fetch: SourceFetchFn;
+}
+/** Result of one agent invocation against one WorkItem. */
+export interface AgentRunResult {
+    item: WorkItem;
+    trajectory: TrajectoryStep[];
+    output: string;
+    runId: string | null;
+    /** Clustering key for consolidation (derived from cti / diagnosis). */
+    signature: string;
+    /**
+     * Run-correlation ids (currently the agent `runId` == OTel `gen_ai.request.id`),
+     * used to look up this run's spans in the Traces UI / as PR evidence — these are
+     * correlation handles, not raw OTel trace ids.
+     */
+    traceIds: string[];
+}
+export interface StagedItem {
+    item: WorkItem;
+    run: AgentRunResult;
+    signature: string;
+}
+/** A group of similar staged fixes → one consolidated PR. */
+export interface Cluster {
+    label: string;
+    signature: string;
+    items: StagedItem[];
+    tickets: WorkItem[];
+    traceIds: string[];
+    /** Placeholder fix artifact — the real derivation is a downstream node. */
+    fix: {
+        summary: string;
+    };
+}
+export type WritesMode = 'shadow' | 'live';
+export interface RunAgentOptions {
+    /** Cumulative feedback injected into the agent's context this run. */
+    feedback?: FeedbackLedger;
+    /**
+     * 'shadow' (default): [READ] real, [WRITE] proposed-only. Instructs the agent not
+     * to mutate; actual enforcement is connector- and human-gated (PRs are merged by a
+     * human) — not guaranteed by this option alone.
+     */
+    writes?: WritesMode;
+}
+export interface WorkflowConfig {
+    /** Agent key resolved from agent-health config (connector). */
+    agent: string;
+    /** Max agent calls in flight (cost + blast-radius cap). Default 1. */
+    concurrency?: number;
+    /** Evaluator id used as the profiling rubric in Step B. */
+    evaluator?: string;
+    /** The agent's own repo (for improvement PRs). */
+    repo?: string;
+}
+export interface PRRequest {
+    title: string;
+    body?: string;
+    repo?: string;
+    evidence?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/dist/lib/workflow/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../workflow/types.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,cAAc,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2EAA2E;IAC3E,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/lib/dist/lib/workflow/types.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/dist/lib/workflow/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../workflow/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/lib/dist/lib/workflow/workflow.d.ts

@@ -0,0 +1,119 @@
+/**
+ * workflow() — a deterministic series of steps with stochastic agent nodes.
+ *
+ * The shell (steps, concurrency fan-out, ledger, staging, consolidation) is
+ * deterministic; the only non-deterministic nodes are the agent calls
+ * (`runAgent`, and the Step-B `deriveAgentEdits`). This mirrors durable
+ * workflow engines: deterministic control flow, stochastic activities.
+ *
+ * @example
+ * ```ts
+ * export default workflow('oncall-queue-and-improve', { agent: 'aos-oncall', concurrency: 4 })
+ *   .step('fix-the-queue', async (wf) => {
+ *     await wf.forEach(queue, { since: '24h' }, async (ticket) => {
+ *       const run = await wf.runAgent(ticket, { feedback: wf.ledger(), writes: 'shadow' });
+ *       wf.stage({ item: ticket, run });
+ *     });
+ *   })
+ *   .step('consolidate-and-pr', async (wf) => {
+ *     for (const c of await wf.consolidate(wf.staged()))
+ *       await wf.raisePR(c.fix, { title: `fix: ${c.label}`, body: wf.ledger().render() });
+ *   });
+ * ```
+ */
+import type { AgentRunResult, Cluster, PRRequest, RunAgentOptions, SourceHandle, StagedItem, WorkItem, WorkflowConfig } from './types.js';
+import { FeedbackLedger } from './ledger.js';
+import { type SessionProfile, type AgentEdit, type ReasonFn } from './stepB.js';
+import type { Span } from '../../types/index.js';
+/** Seams the runner/CLI/tests can inject (agent invocation, PR raising, steering). */
+export interface WorkflowRunOptions {
+    since?: string;
+    /** Overrides config.concurrency for this run. */
+    concurrency?: number;
+    /** Cap total items processed (e.g. `--limit 5` for a smoke loop). */
+    limit?: number;
+    mode?: 'new' | 'existing' | 'both';
+    /** Don't raise PRs — log what would be raised. Default true for safety. */
+    dryRun?: boolean;
+    /** Replace the agent invocation (tests / headless). Defaults to connector resolution. */
+    invoke?: (item: WorkItem, opts: RunAgentOptions) => Promise<AgentRunResult>;
+    /** Replace PR raising (tests / GitHub wiring). Defaults to a dry-run log. */
+    onPR?: (pr: PRRequest, artifact: unknown) => Promise<void>;
+    /** Per-item human steering — return text to append to the ledger. */
+    steer?: (run: AgentRunResult) => Promise<string | void> | string | void;
+    /** Resolve guided sessions to profile. Default: warns + []. */
+    fetchGuidedSessions?: (opts: {
+        since?: string;
+    }) => Promise<Array<{
+        sessionId: string;
+        spans: Span[];
+        serviceName?: string;
+        evaluator?: {
+            id: string;
+            systemPrompt?: string;
+        };
+    }>>;
+    /** Fetch a session's spans by id (when profile() is called with just a sessionId). */
+    fetchSpans?: (sessionId: string) => Promise<Span[]>;
+    /** Reasoner for deriveAgentEdits. Default: `claude -p`. */
+    reason?: ReasonFn;
+}
+export interface ForEachOptions {
+    since?: string;
+    concurrency?: number;
+    limit?: number;
+}
+export interface WorkflowContext {
+    readonly config: WorkflowConfig;
+    /** The run's cumulative feedback ledger (stable across steps). */
+    ledger(): FeedbackLedger;
+    /** Fan out over a source at bounded concurrency, invoking `handler` per item. */
+    forEach(handle: SourceHandle, opts: ForEachOptions, handler: (item: WorkItem) => Promise<void>): Promise<void>;
+    /** Invoke the agent once for a work item. */
+    runAgent(item: WorkItem, opts?: RunAgentOptions): Promise<AgentRunResult>;
+    /** Stash a candidate fix without raising a PR. */
+    stage(s: {
+        item: WorkItem;
+        run: AgentRunResult;
+        signature?: string;
+    }): void;
+    staged(): StagedItem[];
+    /** Cluster staged fixes → one per fix-class. */
+    consolidate(staged: StagedItem[]): Promise<Cluster[]>;
+    /** Raise (or, in dry-run, log) a PR. */
+    raisePR(artifact: unknown, pr: PRRequest): Promise<void>;
+    guidedSessions(opts?: {
+        since?: string;
+    }): Promise<SessionProfile[]>;
+    profile(session: {
+        sessionId: string;
+        spans?: Span[];
+        serviceName?: string;
+        evaluator?: {
+            id: string;
+            systemPrompt?: string;
+        };
+    }): Promise<SessionProfile>;
+    deriveAgentEdits(profiles: SessionProfile[], opts?: {
+        repo?: string;
+        ledger?: FeedbackLedger;
+    }): Promise<AgentEdit[]>;
+}
+export interface WorkflowResult {
+    name: string;
+    staged: StagedItem[];
+    clusters: Cluster[];
+    ledgerSize: number;
+    prsRaised: number;
+    peakConcurrency: number;
+}
+type StepFn = (wf: WorkflowContext) => Promise<void> | void;
+export interface Workflow {
+    readonly name: string;
+    readonly config: WorkflowConfig;
+    step(name: string, fn: StepFn): Workflow;
+    run(opts?: WorkflowRunOptions): Promise<WorkflowResult>;
+}
+export declare function workflow(name: string, config: WorkflowConfig): Workflow;
+export {};
+//# sourceMappingURL=workflow.d.ts.map

package/lib/dist/lib/workflow/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../workflow/workflow.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/workflow/workflow.js

@@ -0,0 +1,195 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FeedbackLedger } from './ledger.js';
+import { mapPool } from './pool.js';
+import { consolidate as consolidateFn } from './consolidate.js';
+import { profileSpans, deriveAgentEdits as deriveAgentEditsFn, } from './stepB.js';
+/** Derive a clustering signature for a run (cti → diagnosis line → unknown). */
+function deriveSignature(item, output) {
+    const cti = item.meta?.['cti'];
+    if (typeof cti === 'string' && cti.trim())
+        return cti.trim();
+    const firstLine = (output || '').split('\n').map((l) => l.trim()).find(Boolean);
+    return firstLine ? firstLine.slice(0, 80) : 'unknown';
+}
+/** Default agent invocation: resolve the connector from config and execute. */
+async function connectorInvoke(config, item, opts) {
+    const [{ loadConfig }, { getConnectorForAgent }] = await Promise.all([
+        import('../../lib/config/index.js'),
+        import('../../services/connectors/registry.js'),
+    ]);
+    // Importing the connectors barrel auto-registers the browser-safe connectors
+    // (agui, mock, rest, ...). server.js adds the server-only ones (claude-code,
+    // subprocess, strands). Both are needed depending on the agent's connector.
+    await import('../../services/connectors/index.js');
+    try {
+        await import('../../services/connectors/server.js');
+    }
+    catch {
+        /* server-only connectors unavailable in this context — browser-safe still work */
+    }
+    const resolved = await loadConfig();
+    const agent = resolved.agents.find((a) => a.key === config.agent || a.name.toLowerCase() === config.agent.toLowerCase());
+    if (!agent) {
+        throw new Error(`workflow agent '${config.agent}' not found in config. ` +
+            `Define it in agent-health.config.ts (connectorType: 'claude-code' for aos-oncall).`);
+    }
+    // Inject cumulative feedback as context the agent reads this run.
+    const feedbackText = opts.feedback?.render();
+    const context = feedbackText
+        ? [{ description: 'Cumulative oncall feedback', value: feedbackText }]
+        : [];
+    const connector = getConnectorForAgent(agent);
+    const testCase = {
+        id: item.id,
+        name: item.id,
+        description: '',
+        initialPrompt: item.prompt,
+        context,
+    };
+    const modelId = Object.keys(resolved.models)[0] || 'claude-sonnet';
+    const response = await connector.execute(agent.endpoint, { testCase, modelId, connectorConfig: agent.connectorConfig }, { type: 'none' });
+    const output = response.trajectory
+        .filter((s) => s.type === 'response' || s.type === 'assistant')
+        .map((s) => s.content || '')
+        .join('\n')
+        .trim();
+    return {
+        item,
+        trajectory: response.trajectory,
+        output,
+        runId: response.runId,
+        signature: deriveSignature(item, output),
+        traceIds: response.runId ? [response.runId] : [],
+    };
+}
+export function workflow(name, config) {
+    const steps = [];
+    const wf = {
+        name,
+        config,
+        step(stepName, fn) {
+            steps.push({ name: stepName, fn });
+            return wf;
+        },
+        async run(runOpts = {}) {
+            const ledger = new FeedbackLedger();
+            const stagedItems = [];
+            let clusters = [];
+            let prsRaised = 0;
+            const stats = { peakConcurrency: 0 };
+            const dryRun = runOpts.dryRun ?? true;
+            const invoke = runOpts.invoke ?? ((item, o) => connectorInvoke(config, item, o));
+            const ctx = {
+                config,
+                ledger: () => ledger,
+                async forEach(handle, opts, handler) {
+                    const since = opts.since ?? runOpts.since;
+                    const all = await handle.fetch({ since });
+                    // Dedup on id, then cap with limit (CLI --limit / opts.limit).
+                    const seen = new Set();
+                    const deduped = all.filter((i) => {
+                        if (seen.has(i.id))
+                            return false;
+                        seen.add(i.id);
+                        return true;
+                    });
+                    const limit = opts.limit ?? runOpts.limit;
+                    // Only slice for a finite, non-negative limit; ignore NaN / negative
+                    // (a bad --limit) rather than silently processing 0 or odd slices.
+                    const items = typeof limit === 'number' && Number.isFinite(limit) && limit >= 0
+                        ? deduped.slice(0, limit)
+                        : deduped;
+                    const concurrency = opts.concurrency ?? runOpts.concurrency ?? config.concurrency ?? 1;
+                    await mapPool(items, concurrency, (item) => handler(item), stats);
+                },
+                runAgent(item, opts = {}) {
+                    return invoke(item, { writes: 'shadow', ...opts });
+                },
+                stage(s) {
+                    const signature = s.signature ?? s.run.signature;
+                    stagedItems.push({ item: s.item, run: s.run, signature });
+                },
+                staged: () => stagedItems,
+                async consolidate(staged) {
+                    clusters = await consolidateFn(staged);
+                    return clusters;
+                },
+                async raisePR(artifact, pr) {
+                    prsRaised++;
+                    if (runOpts.onPR) {
+                        await runOpts.onPR(pr, artifact);
+                        return;
+                    }
+                    if (dryRun) {
+                        // eslint-disable-next-line no-console
+                        console.log(`[workflow:${name}] (dry-run) would raise PR: ${pr.title}` +
+                            (pr.repo ? ` → ${pr.repo}` : ''));
+                        return;
+                    }
+                    throw new Error('raisePR: no onPR handler and dryRun=false. Wire a GitHub PR ' +
+                        'handler via run({ onPR }) or run with --dry-run.');
+                },
+                // ── Step B — wired onto the #267 profile primitives ──
+                async guidedSessions(opts = {}) {
+                    if (!runOpts.fetchGuidedSessions) {
+                        console.warn(`[workflow:${name}] guidedSessions(): no fetchGuidedSessions seam provided — ` +
+                            'returning []. Wire run({ fetchGuidedSessions }) or pass profiles directly.');
+                        return [];
+                    }
+                    const sessions = await runOpts.fetchGuidedSessions({ since: opts.since ?? runOpts.since });
+                    return sessions.map((s) => profileSpans(s.sessionId, s.spans, { serviceName: s.serviceName, evaluator: s.evaluator }));
+                },
+                async profile(session) {
+                    let spans = session.spans;
+                    if (!spans) {
+                        if (!runOpts.fetchSpans) {
+                            throw new Error('wf.profile(): session has no spans and no fetchSpans seam was provided. ' +
+                                'Pass { spans } or run({ fetchSpans }).');
+                        }
+                        spans = await runOpts.fetchSpans(session.sessionId);
+                    }
+                    return profileSpans(session.sessionId, spans, {
+                        serviceName: session.serviceName,
+                        evaluator: session.evaluator,
+                    });
+                },
+                async deriveAgentEdits(profiles, opts = {}) {
+                    return deriveAgentEditsFn(profiles, {
+                        repo: opts.repo ?? config.repo,
+                        ledger: opts.ledger ?? ledger,
+                        reason: runOpts.reason,
+                    });
+                },
+            };
+            // Expose steer so a step's handler can append per-item feedback.
+            // (Steps call ctx.runAgent then optionally ctx.ledger().append(...).)
+            if (runOpts.steer) {
+                const baseRunAgent = ctx.runAgent.bind(ctx);
+                ctx.runAgent = async (item, opts) => {
+                    const run = await baseRunAgent(item, opts);
+                    const fb = await runOpts.steer(run);
+                    if (typeof fb === 'string' && fb.trim()) {
+                        ledger.append(fb, { ticketId: item.id });
+                    }
+                    return run;
+                };
+            }
+            for (const s of steps) {
+                await s.fn(ctx);
+            }
+            return {
+                name,
+                staged: stagedItems,
+                clusters,
+                ledgerSize: ledger.size,
+                prsRaised,
+                peakConcurrency: stats.peakConcurrency,
+            };
+        },
+    };
+    return wf;
+}
+//# sourceMappingURL=workflow.js.map

package/lib/dist/lib/workflow/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../../workflow/workflow.ts"],"names":[],"mappings":"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"}

package/lib/dist/services/agent/aguiConverter.d.ts

@@ -0,0 +1,50 @@
+import { TrajectoryStep } from '../../types/index.js';
+import { AGUIEvent } from '../../types/agui.js';
+export declare class AGUIToTrajectoryConverter {
+    private currentTextMessage;
+    private activeTools;
+    private hasEmittedAction;
+    private runFinished;
+    private pendingTextIsResponse;
+    private runId;
+    private threadId;
+    private isThinking;
+    private currentThinkingMessage;
+    /**
+     * Process a single AG UI event and convert it to TrajectoryStep(s)
+     * Returns an array of steps (usually 0 or 1, sometimes more)
+     */
+    processEvent(event: AGUIEvent): TrajectoryStep[];
+    private handleRunStarted;
+    getRunId(): string | null;
+    getThreadId(): string | null;
+    private handleRunFinished;
+    private handleRunError;
+    private handleTextMessageStart;
+    private handleTextMessageContent;
+    private handleTextMessageEnd;
+    private handleActivitySnapshot;
+    private handleActivityDelta;
+    private handleToolCallStart;
+    private handleToolCallArgs;
+    /**
+     * Handle TOOL_CALL_END - emits the action step with complete args
+     * This is called when the agent is done sending tool call arguments
+     * and expects the client to execute the tool
+     */
+    private handleToolCallEnd;
+    private handleToolCallResult;
+    private handleThinkingStart;
+    private handleThinkingEnd;
+    private handleThinkingTextMessageStart;
+    private handleThinkingTextMessageContent;
+    private handleThinkingTextMessageEnd;
+    private extractToolName;
+    private parseToolArgs;
+}
+/**
+ * Compute trajectory from raw AG-UI events
+ * Use this to derive trajectory on-demand instead of storing both
+ */
+export declare function computeTrajectoryFromRawEvents(rawEvents: AGUIEvent[]): TrajectoryStep[];
+//# sourceMappingURL=aguiConverter.d.ts.map

package/lib/dist/services/agent/aguiConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aguiConverter.d.ts","sourceRoot":"","sources":["../../../../services/agent/aguiConverter.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,cAAc,EAAkB,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAiB,MAAM,cAAc,CAAC;AAoCxD,qBAAa,yBAAyB;IACpC,OAAO,CAAC,kBAAkB,CAAiC;IAC3D,OAAO,CAAC,WAAW,CAAqC;IACxD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAuB;IAGvC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,sBAAsB,CAAqC;IAEnE;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,EAAE;IAuFhD,OAAO,CAAC,gBAAgB;IAgBxB,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,oBAAoB;IAuC5B,OAAO,CAAC,sBAAsB;IA4B9B,OAAO,CAAC,mBAAmB;IA0B3B,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,kBAAkB;IAW1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAyCzB,OAAO,CAAC,oBAAoB;IA8D5B,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,8BAA8B;IAStC,OAAO,CAAC,gCAAgC;IAOxC,OAAO,CAAC,4BAA4B;IA4BpC,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,aAAa;CA8BtB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,cAAc,EAAE,CAgBvF"}