@tangle-network/agent-runtime 0.105.0 → 0.106.0

package/dist/environment-provider.d.ts

@@ -1,78 +1,2 @@
-import { AgentProfile, AgentProfileValidationResult } from '@tangle-network/agent-interface';
-import { AgentEnvironmentProvider, CreateAgentEnvironmentInput, AgentTurnInput, AgentEnvironmentCapabilities, AgentProfileRef } from '@tangle-network/agent-interface/environment-provider';
-export { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentEvent, AgentEnvironmentProvider, AgentEnvironmentQuery, AgentEnvironmentStatus, AgentEnvironmentSummary, AgentProfileRef, AgentSession, AgentSessionRef, AgentSessionStatus, AgentTurnInput, AgentTurnResult, CheckpointRef, CheckpointRequest, CreateAgentEnvironmentInput, ExecRequest, ExecResult, ForkRequest, PlacementInfo, ResourceRequest, WorkspaceRequest } from '@tangle-network/agent-interface/environment-provider';
-import { SandboxClient, CreateSandboxOptions, BackendType } from '@tangle-network/sandbox';
-import { R as Runtime, E as ExecutorFactory } from './types-CvNwMzQt.js';
-import { a as SandboxClient$1 } from './types-BCoemcXU.js';
-import '@tangle-network/agent-eval';
-import './types-BwoZWq-i.js';
-
-interface CreateTangleSandboxExactProcessProviderOptions {
-    name?: string;
-}
-/**
- * Adapt Tangle Sandbox's managed control runtime to Runtime's exact-process provider.
- *
- * The adapter deliberately exposes no ordinary agent environment: an exact experiment
- * must start a fresh Sandbox with no managed agent and launch its declared argv directly.
- */
-declare function createTangleSandboxExactProcessProvider(client: SandboxClient, options?: CreateTangleSandboxExactProcessProviderOptions): AgentEnvironmentProvider;
-
-/** Provider object or registry name accepted by runtime provider adapters.
- * @experimental */
-type AgentEnvironmentProviderRef = AgentEnvironmentProvider | string;
-/** In-memory registry for named `AgentEnvironmentProvider` instances.
- * @experimental */
-interface AgentEnvironmentProviderRegistry {
-    register(provider: AgentEnvironmentProvider, options?: {
-        replace?: boolean;
-    }): void;
-    has(name: string): boolean;
-    get(name: string): AgentEnvironmentProvider | undefined;
-    require(name: string): AgentEnvironmentProvider;
-    names(): string[];
-    providers(): AgentEnvironmentProvider[];
-    capabilities(name: string): Promise<AgentEnvironmentCapabilities>;
-}
-/** Create a registry that resolves provider names to concrete provider instances.
- * @experimental */
-declare function createAgentEnvironmentProviderRegistry(providers?: Iterable<AgentEnvironmentProvider>): AgentEnvironmentProviderRegistry;
-/** Resolve a provider instance or registry name, failing loudly when a name is unknown.
- * @experimental */
-declare function resolveAgentEnvironmentProvider(provider: AgentEnvironmentProviderRef, registry?: AgentEnvironmentProviderRegistry): AgentEnvironmentProvider;
-/** Options for exposing an `AgentEnvironmentProvider` through the legacy sandbox client port.
- * @experimental */
-interface ProviderAsSandboxClientOptions {
-    defaults?: Partial<CreateAgentEnvironmentInput>;
-    requireTerminalEvent?: boolean;
-    mapCreateOptions?: (options: CreateSandboxOptions | undefined) => Partial<CreateAgentEnvironmentInput>;
-}
-/** Adapt a neutral environment provider to the `SandboxClient` interface used by existing loop paths.
- * @experimental */
-declare function providerAsSandboxClient(provider: AgentEnvironmentProvider, options?: ProviderAsSandboxClientOptions): SandboxClient$1;
-/** Options for wrapping the current Tangle sandbox client as an environment provider.
- * @experimental */
-interface SandboxClientProviderOptions {
-    name?: string;
-    defaultBackend?: BackendType;
-    capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
-    validateProfile?: (profile: AgentProfileRef) => AgentProfileValidationResult | Promise<AgentProfileValidationResult>;
-    mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
-}
-/** Adapt a `SandboxClient` into the shared `AgentEnvironmentProvider` contract.
- * @experimental */
-declare function sandboxClientAsProvider(client: SandboxClient$1, options?: SandboxClientProviderOptions): AgentEnvironmentProvider;
-/** Options for running a provider as a supervise-mode executor.
- * @experimental */
-interface ProviderExecutorOptions {
-    defaults?: Partial<CreateAgentEnvironmentInput>;
-    runtime?: Runtime;
-    destroyOnSettle?: boolean;
-    requireTerminalEvent?: boolean;
-    taskToTurn?: (task: unknown, specProfile: AgentProfile) => AgentTurnInput;
-}
-/** Adapt an environment provider into an `ExecutorFactory` for `createExecutor`.
- * @experimental */
-declare function providerAsExecutor(provider: AgentEnvironmentProvider, options?: ProviderExecutorOptions): ExecutorFactory<unknown>;
-
-export { type AgentEnvironmentProviderRef, type AgentEnvironmentProviderRegistry, type CreateTangleSandboxExactProcessProviderOptions, type ProviderAsSandboxClientOptions, type ProviderExecutorOptions, type SandboxClientProviderOptions, createAgentEnvironmentProviderRegistry, createTangleSandboxExactProcessProvider, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider };
+import { A as providerAsSandboxClient, C as ProviderAsSandboxClientOptions, D as WorkspaceRequest, E as SandboxClientProviderOptions, F as createTangleSandboxExactProcessProvider, M as sandboxClientAsProvider, N as CreateTangleSandboxExactProcessProviderOptions, O as createAgentEnvironmentProviderRegistry, S as PlacementInfo, T as ResourceRequest, _ as CheckpointRequest, a as AgentEnvironmentProviderRef, b as ExecResult, c as AgentEnvironmentStatus, d as AgentSession, f as AgentSessionRef, g as CheckpointRef, h as AgentTurnResult, i as AgentEnvironmentProvider, j as resolveAgentEnvironmentProvider, k as providerAsExecutor, l as AgentEnvironmentSummary, m as AgentTurnInput, n as AgentEnvironmentCapabilities, o as AgentEnvironmentProviderRegistry, p as AgentSessionStatus, r as AgentEnvironmentEvent, s as AgentEnvironmentQuery, t as AgentEnvironment, u as AgentProfileRef, v as CreateAgentEnvironmentInput, w as ProviderExecutorOptions, x as ForkRequest, y as ExecRequest } from "./environment-provider-IUGU3epE.js";
+export { type AgentEnvironment, type AgentEnvironmentCapabilities, type AgentEnvironmentEvent, type AgentEnvironmentProvider, AgentEnvironmentProviderRef, AgentEnvironmentProviderRegistry, type AgentEnvironmentQuery, type AgentEnvironmentStatus, type AgentEnvironmentSummary, type AgentProfileRef, type AgentSession, type AgentSessionRef, type AgentSessionStatus, type AgentTurnInput, type AgentTurnResult, type CheckpointRef, type CheckpointRequest, type CreateAgentEnvironmentInput, type CreateTangleSandboxExactProcessProviderOptions, type ExecRequest, type ExecResult, type ForkRequest, type PlacementInfo, ProviderAsSandboxClientOptions, ProviderExecutorOptions, type ResourceRequest, SandboxClientProviderOptions, type WorkspaceRequest, createAgentEnvironmentProviderRegistry, createTangleSandboxExactProcessProvider, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider };

package/dist/environment-provider.js

@@ -1,18 +1,2 @@
-import {
-  createAgentEnvironmentProviderRegistry,
-  createTangleSandboxExactProcessProvider,
-  providerAsExecutor,
-  providerAsSandboxClient,
-  resolveAgentEnvironmentProvider,
-  sandboxClientAsProvider
-} from "./chunk-KRBFHMV6.js";
-import "./chunk-3MDZX7YU.js";
-export {
-  createAgentEnvironmentProviderRegistry,
-  createTangleSandboxExactProcessProvider,
-  providerAsExecutor,
-  providerAsSandboxClient,
-  resolveAgentEnvironmentProvider,
-  sandboxClientAsProvider
-};
-//# sourceMappingURL=environment-provider.js.map
+import { a as sandboxClientAsProvider, i as resolveAgentEnvironmentProvider, n as providerAsExecutor, o as createTangleSandboxExactProcessProvider, r as providerAsSandboxClient, t as createAgentEnvironmentProviderRegistry } from "./environment-provider-CfLUmKmf.js";
+export { createAgentEnvironmentProviderRegistry, createTangleSandboxExactProcessProvider, providerAsExecutor, providerAsSandboxClient, resolveAgentEnvironmentProvider, sandboxClientAsProvider };

package/dist/errors-DEAvWQPy.js

@@ -0,0 +1,111 @@
+import { AgentEvalError, AgentEvalError as AgentEvalError$1, ConfigError, JudgeError, NotFoundError, ValidationError } from "@tangle-network/agent-eval";
+//#region src/errors.ts
+/**
+*
+* Error taxonomy for `@tangle-network/agent-runtime`.
+*
+* Public contract: every error this package throws as part of its consumer-
+* facing API either extends `AgentEvalError` (re-exported here for ergonomic
+* `instanceof` checks at the runtime boundary) or extends one of the
+* runtime-specific subclasses below.
+*
+* Internal invariant guards (`throw new Error('this should never happen')`)
+* remain plain `Error` — they are programmer-mistake assertions, not
+* consumer-catchable contract failures.
+*
+* Subclassing strategy: where a runtime-specific failure maps cleanly to an
+* agent-eval code (validation, config, not_found), we re-use the agent-eval
+* subclass. Runtime-only failure modes (session resume against the wrong
+* backend, backend transport errors) get fresh subclasses that still carry an
+* `AgentEvalErrorCode` so cross-package handlers can pattern-match without
+* importing the runtime.
+*
+* @stable
+*/
+/**
+*
+* Caller asked to resume a session against a backend whose `kind` does not
+* match the session's recorded backend. This is a routing bug — the same
+* session id was reused across two different backend implementations — and
+* is not retryable without picking the right backend.
+*
+* @stable
+*/
+var SessionMismatchError = class extends AgentEvalError {
+	sessionBackend;
+	requestedBackend;
+	constructor(sessionBackend, requestedBackend, options) {
+		super("validation", `Cannot resume ${sessionBackend} session with ${requestedBackend} backend`, options);
+		this.sessionBackend = sessionBackend;
+		this.requestedBackend = requestedBackend;
+	}
+};
+/**
+*
+* A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success
+* status. Distinct from `JudgeError` (which is structural / unrecoverable)
+* because backend failures are sometimes retryable and consumers may want to
+* branch on the upstream status code.
+*
+* @stable
+*/
+var BackendTransportError = class extends AgentEvalError {
+	backend;
+	status;
+	/**
+	* Truncated upstream response body (≤2 KiB) when available. Diagnostic
+	* only — surfaces in `backend_error.error.body` and `final.error.body`
+	* so operators can see "free_tier_limit", "invalid_api_key", etc. without
+	* cracking the log line open.
+	*/
+	body;
+	constructor(backend, message, options) {
+		super("config", message, options);
+		this.backend = backend;
+		this.status = options?.status;
+		this.body = options?.body;
+	}
+};
+/**
+*
+* A runtime-run lifecycle method was called in an order the state machine does
+* not allow: `persist()` before `complete()`, `complete()` twice, etc.
+*
+* @stable
+*/
+var RuntimeRunStateError = class extends AgentEvalError {
+	constructor(message, options) {
+		super("validation", message, options);
+	}
+};
+/**
+*
+* The dynamic-loop planner returned an unusable topology move — the LLM emitted
+* no parseable envelope, an unknown `kind`, or a structurally-invalid move
+* (e.g. a fanout with zero tasks). This is a structural failure of the
+* agent-authored topology, not a config mistake: the planner ran but its output
+* cannot drive the kernel. Carries `validation` so cross-package handlers can
+* pattern-match without importing the runtime. Fail loud — never substitute a
+* default move, or the loop silently runs a topology nobody chose.
+*
+* @stable
+*/
+var PlannerError = class extends AgentEvalError {
+	constructor(message, options) {
+		super("validation", message, options);
+	}
+};
+/**
+* The analyst loop could not read or run over a round's trace — e.g. an empty round
+* (no iterations to analyze) or a malformed trace projection. Fail loud: a silent empty
+* store would mask a broken capture path and the driver would steer on nothing.
+*/
+var AnalystError = class extends AgentEvalError {
+	constructor(message, options) {
+		super("validation", message, options);
+	}
+};
+//#endregion
+export { JudgeError as a, RuntimeRunStateError as c, ConfigError as i, SessionMismatchError as l, AnalystError as n, NotFoundError as o, BackendTransportError as r, PlannerError as s, AgentEvalError$1 as t, ValidationError as u };
+
+//# sourceMappingURL=errors-DEAvWQPy.js.map

package/dist/errors-DEAvWQPy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-DEAvWQPy.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n *\n * Error taxonomy for `@tangle-network/agent-runtime`.\n *\n * Public contract: every error this package throws as part of its consumer-\n * facing API either extends `AgentEvalError` (re-exported here for ergonomic\n * `instanceof` checks at the runtime boundary) or extends one of the\n * runtime-specific subclasses below.\n *\n * Internal invariant guards (`throw new Error('this should never happen')`)\n * remain plain `Error` — they are programmer-mistake assertions, not\n * consumer-catchable contract failures.\n *\n * Subclassing strategy: where a runtime-specific failure maps cleanly to an\n * agent-eval code (validation, config, not_found), we re-use the agent-eval\n * subclass. Runtime-only failure modes (session resume against the wrong\n * backend, backend transport errors) get fresh subclasses that still carry an\n * `AgentEvalErrorCode` so cross-package handlers can pattern-match without\n * importing the runtime.\n *\n * @stable\n */\n\nimport { AgentEvalError } from '@tangle-network/agent-eval'\n\nexport {\n  AgentEvalError,\n  type AgentEvalErrorCode,\n  ConfigError,\n  JudgeError,\n  NotFoundError,\n  ValidationError,\n} from '@tangle-network/agent-eval'\n\n/**\n *\n * Caller asked to resume a session against a backend whose `kind` does not\n * match the session's recorded backend. This is a routing bug — the same\n * session id was reused across two different backend implementations — and\n * is not retryable without picking the right backend.\n *\n * @stable\n */\nexport class SessionMismatchError extends AgentEvalError {\n  readonly sessionBackend: string\n  readonly requestedBackend: string\n\n  constructor(sessionBackend: string, requestedBackend: string, options?: { cause?: unknown }) {\n    super(\n      'validation',\n      `Cannot resume ${sessionBackend} session with ${requestedBackend} backend`,\n      options,\n    )\n    this.sessionBackend = sessionBackend\n    this.requestedBackend = requestedBackend\n  }\n}\n\n/**\n *\n * A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success\n * status. Distinct from `JudgeError` (which is structural / unrecoverable)\n * because backend failures are sometimes retryable and consumers may want to\n * branch on the upstream status code.\n *\n * @stable\n */\nexport class BackendTransportError extends AgentEvalError {\n  readonly backend: string\n  readonly status?: number\n  /**\n   * Truncated upstream response body (≤2 KiB) when available. Diagnostic\n   * only — surfaces in `backend_error.error.body` and `final.error.body`\n   * so operators can see \"free_tier_limit\", \"invalid_api_key\", etc. without\n   * cracking the log line open.\n   */\n  readonly body?: string\n\n  constructor(\n    backend: string,\n    message: string,\n    options?: { cause?: unknown; status?: number; body?: string },\n  ) {\n    super('config', message, options)\n    this.backend = backend\n    this.status = options?.status\n    this.body = options?.body\n  }\n}\n\n/**\n *\n * A runtime-run lifecycle method was called in an order the state machine does\n * not allow: `persist()` before `complete()`, `complete()` twice, etc.\n *\n * @stable\n */\nexport class RuntimeRunStateError extends AgentEvalError {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super('validation', message, options)\n  }\n}\n\n/**\n *\n * The dynamic-loop planner returned an unusable topology move — the LLM emitted\n * no parseable envelope, an unknown `kind`, or a structurally-invalid move\n * (e.g. a fanout with zero tasks). This is a structural failure of the\n * agent-authored topology, not a config mistake: the planner ran but its output\n * cannot drive the kernel. Carries `validation` so cross-package handlers can\n * pattern-match without importing the runtime. Fail loud — never substitute a\n * default move, or the loop silently runs a topology nobody chose.\n *\n * @stable\n */\nexport class PlannerError extends AgentEvalError {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super('validation', message, options)\n  }\n}\n\n/**\n * The analyst loop could not read or run over a round's trace — e.g. an empty round\n * (no iterations to analyze) or a malformed trace projection. Fail loud: a silent empty\n * store would mask a broken capture path and the driver would steer on nothing.\n */\nexport class AnalystError extends AgentEvalError {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super('validation', message, options)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAa,uBAAb,cAA0C,eAAe;CACvD;CACA;CAEA,YAAY,gBAAwB,kBAA0B,SAA+B;EAC3F,MACE,cACA,iBAAiB,eAAe,gBAAgB,iBAAiB,WACjE,OACF;EACA,KAAK,iBAAiB;EACtB,KAAK,mBAAmB;CAC1B;AACF;;;;;;;;;;AAWA,IAAa,wBAAb,cAA2C,eAAe;CACxD;CACA;;;;;;;CAOA;CAEA,YACE,SACA,SACA,SACA;EACA,MAAM,UAAU,SAAS,OAAO;EAChC,KAAK,UAAU;EACf,KAAK,SAAS,SAAS;EACvB,KAAK,OAAO,SAAS;CACvB;AACF;;;;;;;;AASA,IAAa,uBAAb,cAA0C,eAAe;CACvD,YAAY,SAAiB,SAA+B;EAC1D,MAAM,cAAc,SAAS,OAAO;CACtC;AACF;;;;;;;;;;;;;AAcA,IAAa,eAAb,cAAkC,eAAe;CAC/C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,cAAc,SAAS,OAAO;CACtC;AACF;;;;;;AAOA,IAAa,eAAb,cAAkC,eAAe;CAC/C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,cAAc,SAAS,OAAO;CACtC;AACF"}

package/dist/improvement-adapter-Cr5TBSji.d.ts

@@ -0,0 +1,166 @@
+import { o as ImprovementProposalSource } from "./types-Cja5OTGh.js";
+import { AnalystFinding, FindingSubject } from "@tangle-network/agent-eval";
+//#region src/agent/surfaces.d.ts
+/**
+ * Surface declarations. Every path is repo-relative (or absolute) at
+ * `defineAgent` time. At resolution time, paths are joined against the
+ * agent's `repoRoot`.
+ *
+ * `systemPrompt`, `tools`, `personas` are DIRECTORIES; the loop appends
+ * `<section>.md`, `<tool>/README.md`, `<persona-id>.yaml` etc.
+ * `rubric`, `outputSchema` are SINGLE FILES; the loop edits them in
+ * place.
+ *
+ * `knowledge` is the agent-knowledge root (typically `.agent-knowledge`);
+ * `applyKnowledgeWriteBlocks` writes pages relative to it.
+ *
+ * Optional surfaces (`scaffolding`, `memory`, `rag`, `outputSchema`)
+ * can be omitted — the loop will reject findings targeting them with a
+ * clear log message instead of fabricating a path.
+ */
+interface AgentSurfaces {
+  /** Directory containing one markdown file per system-prompt section. */
+  systemPrompt: string;
+  /** Directory containing one subdir per tool (`<tool>/README.md`). */
+  tools: string;
+  /** Single file (TypeScript module) defining the rubric weights + dimensions. */
+  rubric: string;
+  /** Knowledge-base root; typically `.agent-knowledge`. */
+  knowledge: string;
+  /** Directory containing one YAML/JSON file per persona. */
+  personas: string;
+  /** Optional: directory containing scaffolding rules (precondition checks, retry policies). */
+  scaffolding?: string;
+  /** Optional: memory store path (JSONL / SQLite / DB). */
+  memory?: string;
+  /** Optional: directory containing RAG corpora (`<corpus>/<doc-id>.md`). */
+  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`. */
+  absolutePath: string;
+  /** Repo-relative path for PR descriptions, diffs, audit logs. */
+  repoRelativePath: string;
+  /** Whether the path currently exists on disk. */
+  exists: boolean;
+  /** The substrate's intent: edit an existing file or create a new one. */
+  intent: 'edit-existing' | 'create-new';
+}
+/**
+ * Resolve a parsed `FindingSubject` to the file path the substrate
+ * should edit (or create) on disk.
+ *
+ * Returns `null` when:
+ *   - the subject targets a surface the agent didn't declare
+ *     (e.g. `rag:*` when `surfaces.rag` is undefined), OR
+ *   - the subject is a `cluster` (failure-mode emits these as evidence,
+ *     not actionable mutations — they don't route to a file).
+ *
+ * Returns a `ResolvedSurface` with `intent: 'create-new'` when the
+ * subject names a path that doesn't yet exist (e.g. a new wiki page).
+ * The caller chooses whether to honour the create — for tightly-managed
+ * surfaces like `systemPrompt` it's usually a contract violation
+ * (the analyst named a section that doesn't exist); for `knowledge`
+ * it's the whole point.
+ */
+declare function resolveSubjectPath(subject: FindingSubject, surfaces: AgentSurfaces, repoRoot: string): ResolvedSurface | null;
+/**
+ * Validate that every declared surface exists on disk under `repoRoot`.
+ *
+ * Returns an array of `SurfaceValidationIssue` — empty when all required
+ * surfaces resolve. `defineAgent` throws with the issues rendered, so
+ * a misconfigured manifest fails at startup (not at the first finding
+ * the loop produces 20 minutes later).
+ */
+interface SurfaceValidationIssue {
+  surface: keyof AgentSurfaces;
+  path: string;
+  reason: 'missing' | 'not-directory' | 'not-file';
+}
+/** Validate an `AgentSurfaces` map on disk — missing paths fail loud at `defineAgent` time instead of silently skipping self-improvement edits. */
+declare function validateSurfaces(surfaces: AgentSurfaces, repoRoot: string): ReadonlyArray<SurfaceValidationIssue>;
+/** Format a list of surface validation issues into a human-readable error string. */
+declare function renderSurfaceIssues(issues: ReadonlyArray<SurfaceValidationIssue>, repoRoot: string): string;
+//#endregion
+//#region src/agent/improvement-adapter.d.ts
+interface SurfaceImprovementEdit {
+  /** Stable id derived from the source finding so re-proposals are idempotent. */
+  id: string;
+  /** The finding that produced this edit — for revert + audit trail. */
+  sourceFindingId: string;
+  /** Parsed subject; included so the apply step doesn't re-parse. */
+  subject: FindingSubject;
+  /** Resolved on-disk target. */
+  target: ResolvedSurface;
+  /** SHA-256 of the current file content the patch was drafted against. */
+  baseSha256: string;
+  /** Unified-diff patch the LLM drafted (relative to `target.absolutePath`). */
+  patch: string;
+  /** One-line summary the operator sees in the report / PR title. */
+  summary: string;
+  /** Multi-line rationale for the PR body — finding context + LLM reasoning. */
+  rationale: string;
+  /** Carry-forward from the finding so the apply gate can check the threshold. */
+  confidence: number;
+  /** Carry-forward severity for prioritization. */
+  severity: AnalystFinding['severity'];
+}
+interface CreateSurfaceImprovementProposerOptions {
+  surfaces: AgentSurfaces;
+  repoRoot: string;
+  /**
+   * LLM-draft callback. Given a finding + current file content + the
+   * resolved target, returns a unified-diff patch + summary + rationale.
+   *
+   * Required — the substrate doesn't ship a hardcoded prompt; the agent
+   * author picks the model (Haiku for cheap routine drafts, Sonnet for
+   * substantive prompt rewrites, etc.) via this callback.
+   */
+  draftPatch: (input: DraftPatchInput) => Promise<DraftPatchOutput>;
+  /**
+   * When the resolved target doesn't exist, allow the substrate to
+   * CREATE the file (for `knowledge.wiki`, `new-tool` subjects). Default
+   * true for those kinds, false for `system-prompt` / `rubric` / etc.
+   * (named sections that don't exist are a contract violation, not a
+   * scaffolding opportunity).
+   */
+  allowCreateForKinds?: ReadonlyArray<FindingSubject['kind']>;
+}
+interface DraftPatchInput {
+  finding: AnalystFinding;
+  subject: FindingSubject;
+  target: ResolvedSurface;
+  /** Current file content (empty string when `intent === 'create-new'`). */
+  currentContent: string;
+}
+interface DraftPatchOutput {
+  /** Unified diff against the current file content. Empty string skips this finding. */
+  patch: string;
+  /** One-line summary for the operator. */
+  summary: string;
+  /** Multi-line rationale for the PR body. */
+  rationale: string;
+}
+/** Resolve each finding to a real surface and draft a detached patch candidate. */
+declare function createSurfaceImprovementProposer(opts: CreateSurfaceImprovementProposerOptions): ImprovementProposalSource<SurfaceImprovementEdit>;
+//#endregion
+export { createSurfaceImprovementProposer as a, SurfaceValidationIssue as c, validateSurfaces as d, SurfaceImprovementEdit as i, renderSurfaceIssues as l, DraftPatchInput as n, AgentSurfaces as o, DraftPatchOutput as r, ResolvedSurface as s, CreateSurfaceImprovementProposerOptions as t, resolveSubjectPath as u };
+//# sourceMappingURL=improvement-adapter-Cr5TBSji.d.ts.map