@tangle-network/agent-runtime 0.91.0 → 0.92.0

package/dist/improve-CUVCq7xg.d.ts

@@ -0,0 +1,152 @@
+import { Scenario, SelfImproveOptions, SurfaceProposer, SelfImproveResult } from '@tangle-network/agent-eval/contract';
+import { AgentProfile } from '@tangle-network/agent-interface';
+import { L as LocalHarness } from './local-harness-dcD5WTTr.js';
+import { V as Verifier, C as CandidateGenerator } from './agentic-generator-B8oeE2Yv.js';
+
+/**
+ *
+ * `improve` — the ONE public, surface-pluggable RSI verb.
+ *
+ * A thin facade over agent-eval's `selfImprove` (the held-out-gated closed
+ * loop). It removes the two things a caller otherwise has to know to drive the
+ * loop by hand: WHICH `MutableSurface` of the profile is being optimized, and
+ * WHICH `SurfaceProposer` mutates that surface. You name a `surface`; the
+ * facade picks the matching default proposer, extracts the baseline surface from
+ * the profile, runs `selfImprove`, and (on a ship verdict) writes the promoted
+ * winner back into the corresponding profile field.
+ *
+ *   - `surface: 'prompt'` → `gepaProposer` mutates `profile.prompt.systemPrompt`.
+ *   - `surface: 'skills'` → `skillOptProposer` mutates a skills document string.
+ *   - `surface: 'agent-profile'` → caller-supplied proposer mutates the complete
+ *     canonical AgentProfile JSON in one candidate.
+ *   - `surface: 'rollout-policy'` → `rolloutPolicyProposer` mutates the
+ *     inference-time `StructuralRolloutPolicy` dials ({ k, repairRounds, testgen })
+ *     persisted in `profile.extensions['structural-rollout']` — deterministic
+ *     bounded neighbor enumeration; the held-out gate does the deciding. No-op
+ *     (nothing proposed, nothing shipped) when the profile has no such extension.
+ *   - `surface` ∈ {`tools`, `mcp`, `hooks`, `subagents`, `workflow`, `agent-profile`, `code`} → no zero-config default
+ *     proposer exists (a code/config proposer needs caller-supplied wiring — a
+ *     worktree repo root, a candidate generator, a serializer). The facade
+ *     requires an explicit `opts.generator` for these and throws a `ConfigError`
+ *     otherwise. This is a designed boundary, not a missing default: there is
+ *     no safe value the facade could invent for those surfaces. Code also
+ *     requires `opts.code.repoRoot` so its incumbent is a real isolated checkout.
+ *
+ * Everything else (`scenarios`, `judge`, `agent`, `budget`, `llm`) passes
+ * straight through to `selfImprove`.
+ *
+ * @experimental
+ */
+
+/** The agent-profile lever `improve` optimizes. Mirrors the AgentProfile-law
+ *  profile levers; `code` is the implementation-tier surface, `rollout-policy`
+ *  the inference-time structuralRollout dials
+ *  (`profile.extensions['structural-rollout']`). */
+type ImproveSurface = 'prompt' | 'skills' | 'tools' | 'mcp' | 'hooks' | 'subagents' | 'workflow' | 'agent-profile' | 'code' | 'rollout-policy';
+type ImproveOptions<TScenario extends Scenario, TArtifact> = Omit<SelfImproveOptions<TScenario, TArtifact>, 'analyzeGeneration' | 'baselineSurface' | 'findings' | 'gate' | 'proposer'> & {
+    /** Which profile lever to optimize. Default `'prompt'`. Selects the default
+     *  generator + the baseline-surface extraction shape. */
+    surface?: ImproveSurface;
+    /** The `SurfaceProposer` that mutates the surface. When unset, the facade
+     *  picks the default for `surface` (`gepaProposer` for prompt, `skillOptProposer`
+     *  for skills); surfaces with no default REQUIRE this (fail-loud otherwise). */
+    generator?: SurfaceProposer;
+    /** Gate mode. `'holdout'` (default) runs the held-out promotion gate;
+     *  `'none'` is a baseline-only run (`budget.generations = 0`). */
+    gate?: 'holdout' | 'none';
+    /** Restrict the run to this subset of models. When set, the reflection model
+     *  (`llm.model`, or the default when unset) must be a member, or `improve()` throws
+     *  a `ConfigError` before the generator is built. Unset = unrestricted. */
+    allowedModels?: readonly string[];
+    /** Per-generation findings producer passthrough (see selfImprove.analyzeGeneration).
+     *  DEFAULT: the built-in failure distiller — after each generation it turns the
+     *  worst-scoring/errored cells into structured findings ({ scenario, composite,
+     *  notes, error }) for the NEXT proposal round, so the proposer reasons over what
+     *  actually failed instead of a static seed. Pass your own producer (e.g. a
+     *  trace-analyst over the runDir's traces) to replace it; pass `null` to disable
+     *  and keep the static `findings` all the way through. */
+    analyzeGeneration?: SelfImproveOptions<TScenario, TArtifact>['analyzeGeneration'] | null;
+    /** META-HARNESS mode: instead of the ~400-char distilled findings, feed the
+     *  proposer RAW-TRACE FILESYSTEM CONTEXT — the PATHS into the prior generation's
+     *  real run traces under `runDir` (per-cell `spans.jsonl` event logs +
+     *  `cached-result.json` scores + artifacts) plus a `grep`/`cat`-to-diagnose
+     *  instruction — so the coding agent reads the actual failures itself rather than
+     *  a pre-summary. Requires a REAL `runDir` (that is where the traces live).
+     *  Ignored when `analyzeGeneration` is set explicitly (that wins) or is `null`
+     *  (disabled). Equivalent to `analyzeGeneration: rawTraceDistiller()`; this flag
+     *  is the one-line enable. Default `false` (the distiller stays the default). */
+    rawTraceContext?: boolean;
+    /** CODE-surface wiring: name `surface: 'code'`, point at a repo, and the
+     *  facade assembles the whole candidate pipeline — an isolated incumbent plus git worktrees
+     *  (`gitWorktreeAdapter`) driven by `improvementDriver` with the full agentic
+     *  generator (a real coding harness edits each candidate worktree; a `verify`
+     *  hook gates candidates before they are ever measured). Ignored when
+     *  `opts.generator` is supplied. Required for every code run because a real
+     *  repository and base ref are necessary to measure the incumbent. */
+    code?: ImproveCodeOptions;
+    /** SKILLS-surface wiring for real skill-DOCUMENT optimization. Without this,
+     *  `surface: 'skills'` optimizes the profile's skills REFS array (file pointers)
+     *  — which `skillOptProposer` (a document patcher) cannot meaningfully edit.
+     *  Provide the document CONTENT to optimize + a `writeBack` to persist the
+     *  shipped winner (the profile ref points at a file the caller owns). This is
+     *  what makes skillOpt reachable through improve(). */
+    skills?: ImproveSkillsOptions;
+    /** Custom held-back-exam decision. The string `gate` above controls whether
+     *  the exam runs; this callback controls how its evidence decides promotion. */
+    promotionGate?: SelfImproveOptions<TScenario, TArtifact>['gate'];
+};
+interface ImproveSkillsOptions {
+    /** The skill document's current text — the baseline `skillOptProposer` patches. */
+    document: string;
+    /** Persist the shipped winner document (write the file the profile ref points at).
+     *  Called only on a ship verdict. When omitted, the winner is still returned in
+     *  `result.raw.winner.surface` for the caller to materialize. */
+    writeBack?: (winnerDocument: string) => void;
+}
+interface ImproveCodeOptions {
+    /** Repo root candidate worktrees fork from. */
+    repoRoot: string;
+    /** Base ref candidates fork from. Default `main`. */
+    baseRef?: string;
+    /** Directory worktrees are created under. Default `<repoRoot>/.worktrees`. */
+    worktreeDir?: string;
+    /** Coding harness the agentic generator runs in each worktree. Default `claude`. */
+    harness?: LocalHarness;
+    /** Verify a candidate worktree before it becomes a measurable surface; failures
+     *  feed the next shot (see `agenticGenerator.verify` / `commandVerifier`). */
+    verify?: Verifier;
+    /** Per-shot wall-clock timeout for the harness (ms). */
+    timeoutMs?: number;
+    /** Byte-producer override — the test seam and the escape hatch for custom
+     *  candidate production. When set, `harness`/`verify`/`timeoutMs` are unused. */
+    generator?: CandidateGenerator;
+}
+interface ImproveResult<TScenario extends Scenario, TArtifact> {
+    /** The profile after improvement: the winner surface applied back into the
+     *  matching field when the gate shipped, else the input profile unchanged. */
+    profile: AgentProfile;
+    /** True when `gateDecision === 'ship'`. */
+    shipped: boolean;
+    /** Held-out lift (`winner − baseline` composite). */
+    lift: number;
+    /** The five-valued gate verdict from `selfImprove`. */
+    gateDecision: SelfImproveResult<TScenario, TArtifact>['gateDecision'];
+    /** Full `selfImprove` result for advanced inspection. */
+    raw: SelfImproveResult<TScenario, TArtifact>;
+}
+/**
+ * Run the held-out-gated self-improvement loop on ONE profile surface.
+ *
+ * @example Optimize the system prompt, default holdout gate:
+ *
+ *   const out = await improve(profile, findings, {
+ *     surface: 'prompt',
+ *     scenarios,
+ *     judge,
+ *     agent: (surface, scenario, ctx) => runAgent(surface, scenario, ctx.signal),
+ *   })
+ *   if (out.shipped) deploy(out.profile)
+ */
+declare function improve<TScenario extends Scenario, TArtifact>(profile: AgentProfile, findings: unknown[], opts: ImproveOptions<TScenario, TArtifact>): Promise<ImproveResult<TScenario, TArtifact>>;
+
+export { type ImproveSurface as I, type ImproveOptions as a, type ImproveResult as b, type ImproveCodeOptions as c, type ImproveSkillsOptions as d, improve as i };

package/dist/{improvement-adapter-CDR8QNVM.d.ts → improvement-adapter-BieWeK5J.d.ts}

@@ -52,6 +52,22 @@ interface AgentSurfaces {
     rag?: string;
     /** Optional: single file defining the output schema (Zod / JSON Schema). */
     outputSchema?: string;
+    /** Optional: directory containing Agent Skill packages. */
+    skills?: string;
+    /** Optional: directory containing MCP server/tool configuration. */
+    mcp?: string;
+    /** Optional: directory containing hook definitions. */
+    hooks?: string;
+    /** Optional: directory containing subagent definitions. */
+    subagents?: string;
+    /** Optional: directory containing orchestration/workflow policies. */
+    workflows?: string;
+    /** Optional: single file containing rollout-policy settings. */
+    rolloutPolicy?: string;
+    /** Optional: single canonical AgentProfile file. */
+    agentProfile?: string;
+    /** Optional: source root for code findings. */
+    code?: string;
 }
 interface ResolvedSurface {
     /** Absolute filesystem path the operator can `cat` / `vim`. */