@themoltnet/pi-extension 0.13.5 → 0.15.0

package/dist/index.d.ts

@@ -1,8 +1,13 @@
+import { AgentSession } from '@earendil-works/pi-coding-agent';
+import { Api } from '@earendil-works/pi-ai';
 import { BashOperations } from '@earendil-works/pi-coding-agent';
 import { connect } from '@themoltnet/sdk';
 import { EditOperations } from '@earendil-works/pi-coding-agent';
 import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
+import { Model } from '@earendil-works/pi-ai';
 import { ReadOperations } from '@earendil-works/pi-coding-agent';
+import { Skill } from '@earendil-works/pi-coding-agent';
 import { Static } from '@sinclair/typebox';
 import { TArray } from '@sinclair/typebox';
 import { TBoolean } from '@sinclair/typebox';
@@ -26,6 +31,33 @@ import { WriteOperations } from '@earendil-works/pi-coding-agent';
  */
 export declare function activateAgentEnv(agentEnv: Record<string, string | undefined>, repoRoot: string): void;
 
+/**
+ * Construct an in-memory `AgentSession`. The caller is responsible for
+ * eventually invoking `session.prompt(...)` and for tearing down — the
+ * helper does no lifecycle management beyond construction.
+ */
+export declare function buildAgentSession(args: BuildAgentSessionArgs): Promise<AgentSession>;
+
+declare interface BuildAgentSessionArgs {
+    /** Host directory mounted at /workspace inside the VM. */
+    mountPath: string;
+    /** pi auth directory (resolved from `PI_CODING_AGENT_DIR` or `~/.pi/agent`). */
+    piAuthDir: string;
+    /** Resolved pi model handle (provider + model id). */
+    modelHandle: Model<Api>;
+    /** Pre-built customTools array. Caller composes Gondolin + MoltNet + submit tools. */
+    customTools: ToolDefinition[];
+    /** System-prompt fragments appended after pi's defaults. Parent passes the
+     *  runtime instructor; subagents pass their narrower variant. */
+    appendSystemPrompt: string[];
+    /** Skills to advertise in `<available_skills>`. Default: empty list. */
+    skillsOverride?: () => LoadSkillsResult;
+    /** Span attributes merged onto every OTel span the session emits. */
+    otelSpanAttrs: Record<string, string | number | boolean>;
+    /** Agent name for `gen_ai.agent.name` on the root span. */
+    agentName: string;
+}
+
 declare interface ClaimedTask {
     /** The claimed task payload itself. */
     task: Task;
@@ -35,6 +67,31 @@ declare interface ClaimedTask {
     traceHeaders: Record<string, string>;
 }
 
+/**
+ * One context entry. Bytes are inlined: the imposer chose them, and the
+ * task's `inputCid` already pins the entire input — including
+ * `context[]` — so we don't need a separate per-entry hash, fetcher, or
+ * flagged-content gate. Tasks reference rendered packs (or any other
+ * external content) by copying their bytes into `content` at task
+ * creation time.
+ *
+ * - `slug` — short identifier the daemon uses to disambiguate
+ *            entries. For `skill` binding it becomes the directory
+ *            name under the runtime's skill discovery path. Must be
+ *            kebab-case-safe (alphanumeric + dashes/underscores).
+ * - `binding` — how the bytes are delivered to the LLM (see above).
+ * - `content` — the actual bytes (UTF-8 text). Capped at 32 KiB per
+ *               entry; total per-task context bytes are bounded by the
+ *               soft `maxItems` cap and per-binding daemon limits.
+ */
+declare const ContextRef: TObject<    {
+    slug: TString;
+    binding: TUnion<[TLiteral<"skill">, TLiteral<"prompt_prefix">, TLiteral<"user_inline">]>;
+    content: TString;
+}>;
+
+declare type ContextRef = Static<typeof ContextRef>;
+
 export declare function createGondolinBashOps(vm: VM, localCwd: string): BashOperations;
 
 export declare function createGondolinEditOps(vm: VM, localCwd: string): EditOperations;
@@ -57,6 +114,73 @@ export declare function createPiOtelExtension(options?: PiOtelOptions): (pi: Ext
  */
 export declare function createPiTaskExecutor(opts: ExecutePiTaskOptions): (claimedTask: ClaimedTask, reporter: TaskReporter) => Promise<TaskOutput>;
 
+/**
+ * Build the subagent custom tool for a parent session. The handle
+ * exposes the call counter so executors can emit summary telemetry
+ * when the parent terminates.
+ */
+export declare function createSubagentTool(args: CreateSubagentToolArgs): SubagentToolHandle;
+
+export declare interface CreateSubagentToolArgs {
+    /** Host directory mounted at /workspace inside the VM. */
+    mountPath: string;
+    /** pi auth directory the parent resolved. */
+    piAuthDir: string;
+    /** Resolved pi model handle — subagents share it. */
+    modelHandle: Model<Api>;
+    /** Agent name for telemetry. */
+    agentName: string;
+    /**
+     * Custom tools every subagent inherits (Gondolin-routed
+     * Read/Write/Edit/Bash + moltnet_* tools, etc). MUST NOT include
+     * the parent's submit-output tool, the parent's `subagent` tool,
+     * or any other parent-only artefact — the caller is responsible
+     * for filtering. The subagent appends its own submit tool.
+     */
+    inheritedCustomTools: ToolDefinition[];
+    /**
+     * The parent runtime instructor verbatim. Subagents prepend it to
+     * their own short "you are a subagent" preamble so the same
+     * invariants (gh auth, diary discipline, accountable commits)
+     * apply if the subagent takes those actions. The parent's task
+     * description dictates whether they should.
+     */
+    parentRuntimeInstructor: string;
+    parentTaskId: string;
+    parentTaskType: string;
+    parentAttemptN: number;
+    /**
+     * Parent task's cancel signal. When the daemon cancels the parent
+     * task (operator cancel or task-level `runningTimeoutSec` expiry),
+     * each in-flight subagent's inner `session.abort()` is invoked so
+     * it tears down promptly instead of running until its own LLM
+     * call resolves. Mirrors the existing `wireSessionAbort` pattern
+     * the parent session uses.
+     *
+     * Optional only because the test seam can omit it; production
+     * callers (executePiTask) pass `reporter.cancelSignal`.
+     */
+    parentCancelSignal?: AbortSignal;
+    /**
+     * Per-call fallback timeout. Defends against an inner session that
+     * ignores `abort()` for any reason (LLM provider stuck, tool call
+     * hanging on I/O, etc.). When the timeout fires, `session.abort()`
+     * is invoked and the tool returns `isError: true` with a
+     * `subagent_timed_out` reason the parent LLM can recover from.
+     *
+     * Default: 5 minutes. Set to `0` to disable (relying purely on
+     * parentCancelSignal). Negative values are treated as the default.
+     */
+    timeoutMs?: number;
+    /**
+     * Test seam. Production callers leave this undefined and get
+     * `buildAgentSession` from the factory module. Tests inject a mock
+     * that returns a stub session implementing only `prompt()` to
+     * exercise the tool's logic without booting a VM.
+     */
+    buildAgentSession?: (args: BuildAgentSessionArgs) => Promise<AgentSession>;
+}
+
 /**
  * Ensure a cached snapshot exists, building one if needed.
  * Returns the absolute path to the qcow2 checkpoint file.
@@ -91,7 +215,7 @@ export declare interface ExecutePiTaskOptions {
     /** Sandbox overrides (env, VFS shadows, resources). */
     sandboxConfig?: SandboxConfig;
     /**
-     * Forwarded to `buildPromptForTask` for per-type builders. Static
+     * Forwarded to `buildTaskUserPrompt` for per-type builders. Static
      * across tasks. Today no built-in builder needs per-task `extras` —
      * judges fetch their own dependent data via MoltNet tools
      * (`moltnet_get_task`, `moltnet_list_task_attempts`, etc.) at run
@@ -107,6 +231,24 @@ export declare interface ExecutePiTaskOptions {
      * across tasks.
      */
     checkpointPath?: string;
+    /**
+     * Optional callback invoked alongside every `reporter.record()` so
+     * the daemon can mirror task messages into its local logger.
+     * Bound at executor-construction time — use when one task runs per
+     * process (e.g. `once.ts`) and per-task context is known before
+     * the executor is built. For poll mode, prefer `makeOnTurnEvent`
+     * below. If both are set, `makeOnTurnEvent` wins.
+     * See `TurnEventHandler` for payload shape. Defaults to a no-op.
+     */
+    onTurnEvent?: TurnEventHandler;
+    /**
+     * Per-task factory variant for `onTurnEvent`. Invoked once per
+     * task with the claimed task before any emit, so the returned
+     * handler can bind taskId / attemptN into a pino child.
+     * Use in poll mode where N tasks run sequentially in the same
+     * process. See #1078.
+     */
+    makeOnTurnEvent?: TurnEventHandlerFactory;
 }
 
 /**
@@ -121,6 +263,32 @@ export declare function findMainWorktree(): string;
  */
 export declare const HOST_EXEC_DEFAULT_BASE_ENV: ReadonlySet<string>;
 
+export declare interface InjectedTaskContext {
+    /** Refs that were delivered, in declared order, for audit. */
+    injected: ContextRef[];
+    /** Synthetic Skill objects to splice into pi's skillsOverride. */
+    skills: Skill[];
+    /** Prepend this to `appendSystemPrompt`. Empty when nothing
+     *  contributed (omit the array entry rather than pass an empty
+     *  string to keep pi's prompt assembly tidy). */
+    systemPromptPrefix: string;
+    /** Append this to the task user prompt BEFORE `session.prompt()`. */
+    userInlineSuffix: string;
+}
+
+/**
+ * Resolve a task's `input.context[]` and inject the side effects pi
+ * needs. Safe to call with an empty array — returns an inert result.
+ */
+export declare function injectTaskContext(args: InjectTaskContextArgs): Promise<InjectedTaskContext>;
+
+export declare interface InjectTaskContextArgs {
+    /** Empty array (the default for any non-eval task) is a no-op. */
+    context: TaskContext;
+    /** Guest filesystem handle. In production this is `managed.vm.fs`. */
+    fs: VmFsForContext;
+}
+
 export declare function loadCredentials(agentDir: string): VmCredentials;
 
 export declare interface ManagedVm {
@@ -230,6 +398,29 @@ export declare interface SandboxConfig {
 /** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
 export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
 
+export declare interface SubagentToolHandle {
+    /** ToolDefinition to register via `customTools` on the parent session. */
+    readonly tool: ToolDefinition;
+    /** How many times the parent LLM has called this tool. */
+    getCallCount: () => number;
+}
+
+/**
+ * Parameters shape the parent LLM sees when calling the subagent tool.
+ *
+ *   - `task`         — natural-language instructions for the subagent.
+ *                      The parent authors this per call. Must be
+ *                      non-empty.
+ *   - `output_schema` — name of a registered SubagentOutputContract.
+ *                      Resolved at call time; unknown names error.
+ */
+export declare const SubagentToolParameters: TObject<{
+    task: TString;
+    output_schema: TString;
+}>;
+
+export declare type SubagentToolParameters = Static<typeof SubagentToolParameters>;
+
 /**
  * The Task promise body.
  *
@@ -264,6 +455,10 @@ declare const Task: TObject<    {
     imposedByHumanId: TUnion<[TString, TNull]>;
     acceptedAttemptN: TUnion<[TNumber, TNull]>;
     requiredExecutorTrustLevel: TUnion<[TLiteral<"selfDeclared">, TLiteral<"agentSigned">, TLiteral<"releaseVerifiedTool">, TLiteral<"sandboxAttested">]>;
+    allowedExecutors: TArray<TObject<    {
+        provider: TString;
+        model: TString;
+    }>>;
     status: TUnion<[TLiteral<"queued">, TLiteral<"dispatched">, TLiteral<"running">, TLiteral<"completed">, TLiteral<"failed">, TLiteral<"cancelled">, TLiteral<"expired">]>;
     queuedAt: TString;
     completedAt: TUnion<[TString, TNull]>;
@@ -278,6 +473,15 @@ declare const Task: TObject<    {
 
 declare type Task = Static<typeof Task>;
 
+/** Reusable input fragment for any task type. Soft cap at 5 items. */
+declare const TaskContext: TArray<TObject<    {
+    slug: TString;
+    binding: TUnion<[TLiteral<"skill">, TLiteral<"prompt_prefix">, TLiteral<"user_inline">]>;
+    content: TString;
+}>>;
+
+declare type TaskContext = Static<typeof TaskContext>;
+
 declare const TaskMessage: TObject<    {
     taskId: TString;
     attemptN: TNumber;
@@ -410,6 +614,14 @@ declare interface TrackedError {
     timestamp: number;
 }
 
+export declare interface TurnEventHandler {
+    (event: TurnEventKind, summary: Record<string, unknown>): void;
+}
+
+export declare type TurnEventHandlerFactory = (claimedTask: ClaimedTask) => TurnEventHandler;
+
+export declare type TurnEventKind = Parameters<TaskReporter['record']>[0]['kind'];
+
 export declare interface VmConfig {
     /** Absolute path to the qcow2 checkpoint. */
     checkpointPath: string;
@@ -444,4 +656,19 @@ export declare interface VmCredentials {
     githubAppPemFilename: string | null;
 }
 
+/**
+ * Subset of `@earendil-works/gondolin`'s `VmFs` we actually use. We
+ * narrow the dependency surface so unit tests can hand in a
+ * vitest-mocked object without instantiating a real VM. We use `any`
+ * for the options parameter to make this interface bivariantly
+ * compatible with `VmFs` (whose options types differ between
+ * `mkdir` and `writeFile`); the orchestrator only ever calls these
+ * methods with the documented option shape, so the looseness is
+ * confined to this seam.
+ */
+export declare interface VmFsForContext {
+    mkdir: (dirPath: string, options?: any) => Promise<void>;
+    writeFile: (filePath: string, data: string | Uint8Array, options?: any) => Promise<void>;
+}
+
 export { }