@fastagent-sh/fastagent 0.17.0 → 0.18.0

package/dist/deploy/agentcore/plan.js

@@ -396,6 +396,23 @@ exports.handler = async (event, ctx) => {
     if (failed > 0) return { statusCode: 500, body: \`\${failed} alarm(s) failed\\n\` };
     return { statusCode: 200, body: "ok\\n" };
   }
+  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
+  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
+  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
+  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
+  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
+  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
+  // public traffic) are probeable too.
+  if (event.rawPath === "/__fastagent/probe") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!process.env.INGRESS_SECRET || req.auth !== process.env.INGRESS_SECRET) return { statusCode: 403, body: "forbidden\\n" };
+    const r = await invoke({ kind: "probe" });
+    if (r.status !== 200) {
+      console.log(\`probe transport error \${r.status}: \${r.body}\`);
+      return { statusCode: 502, body: "upstream error\\n" };
+    }
+    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
+  }
   // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
   // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
   const webhookBytes = event.body === undefined ? 0

package/dist/deploy/agentcore/run.d.ts

@@ -70,4 +70,10 @@ export declare function parseCheckpointReply(stdout: string): CheckpointReply |
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<AgentcoreRunOutcome>;
+export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<AgentcoreRunOutcome>;

package/dist/deploy/agentcore/run.js

@@ -3,6 +3,66 @@ import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { AUTH_SEED_CHUNK_SIZE, AUTH_SEED_MAX_CHUNKS, cfnParamName, forwarderSource, ingressSessionId, stateBucketName, } from "./plan.js";
 import { zipSingleFile } from "./zip.js";
+/** How long the post-deploy probe waits for the fresh session (image pull + microVM boot + snapshot
+ *  restore + channel construction) before gating with the last answer. */
+const PROBE_TIMEOUT_MS = 120_000;
+const PROBE_INTERVAL_MS = 3_000;
+/**
+ * Drive the forwarder's reserved `/__fastagent/probe` path until it answers, and read the runtime's
+ * STRUCTURED verdict. The path answers on every forwarder topology (a schedule-only URL refuses
+ * ordinary public traffic, so a plain `GET /health` would 404 there), and the verdict rides a
+ * transport-200 JSON body `{ ok, error? }` — the ordinary webhook relay folds a non-200 transport
+ * into an opaque 502, which would strip the very diagnostics this probe exists to carry.
+ *
+ * Outcome policy: `ok:true` verifies the deploy; `ok:false` gates IMMEDIATELY with the runtime's own
+ * error text (construction rejections are cached per session, so polling cannot change the answer);
+ * anything else (unroutable URL, forwarder 4xx/5xx, malformed body) is retried to the deadline —
+ * that budget's job is absorbing cold-start provisioning — and then gates with the last answer seen.
+ */
+async function probeRuntime(probeUrl, auth, fetchImpl, timeoutMs = PROBE_TIMEOUT_MS, intervalMs = PROBE_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    for (;;) {
+        try {
+            const res = await fetchImpl(probeUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ auth }),
+                signal: AbortSignal.timeout(65_000),
+            });
+            const bodyText = await res.text();
+            if (res.status === 200) {
+                let verdict;
+                try {
+                    verdict = JSON.parse(bodyText);
+                }
+                catch {
+                    /* malformed — fall through to retry with it as the last answer */
+                }
+                if (verdict?.ok === true)
+                    return { ok: true };
+                if (verdict?.ok === false) {
+                    const error = typeof verdict.error === "string" ? verdict.error : "unknown error";
+                    return { ok: false, gate: `the deployed runtime failed its probe: ${error} — fix and re-run` };
+                }
+            }
+            const firstLine = bodyText.trim().split("\n")[0] ?? "";
+            last = `${res.status}${firstLine ? ` ${firstLine}` : ""}`;
+        }
+        catch {
+            /* not routable yet (Function URL DNS, cold start) — keep polling until the deadline */
+        }
+        if (Date.now() >= deadline) {
+            return {
+                ok: false,
+                gate: last
+                    ? `the forwarder probe never verified the deployment (last answer: ${last}) — check the runtime logs and re-run`
+                    : "the forwarder URL never answered the probe — check the Function URL / runtime logs and re-run",
+            };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
 /** Stack outputs (`describe-stacks --query "Stacks[0].Outputs"`) → { OutputKey: OutputValue }. */
 export function parseStackOutputs(stdout) {
     try {
@@ -63,7 +123,9 @@ export function parseCheckpointReply(stdout) {
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack) {
+export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe = {}) {
     const gate = (g) => ({ ok: false, gate: g });
     const stack = `fastagent-${plan.name}`;
     const repo = `fastagent/${plan.name}`;
@@ -359,19 +421,42 @@ export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile
                 log("note: no ingress session to stop (first deploy, or already reclaimed)");
             }
             else {
-                log(`warn: could not stop the ingress session — an ACTIVE session may keep serving the PREVIOUS ` +
-                    `image until reclaimed (idle timeout / 8 h ceiling). Stop it manually: aws ${stopCommand.join(" ")}`);
+                // A GATE, not a warning: the probe below reaches the SAME fixed session id, so a session
+                // still running the previous image would answer it and the deploy would claim to have
+                // verified a serving path it never touched. Unable to guarantee the session is fresh =
+                // unable to verify = stop.
                 const firstLine = stderr.trim().split("\n")[0];
-                if (firstLine)
-                    log(`warn: ${firstLine}`);
+                return gate(`could not stop the ingress session — it may still be serving the PREVIOUS image, so the ` +
+                    `deploy cannot verify the new one${firstLine ? ` (${firstLine})` : ""}. ` +
+                    `Stop it manually (aws ${stopCommand.join(" ")}) and re-run`);
             }
         }
     }
+    // 8c. Every forwarder topology MUST carry the ForwarderUrl output — schedule-only and
+    //     selfSchedule-only deployments included, since the probe below is their only construction
+    //     check (there is no boot-time failStartup on this host). A missing output means an edited
+    //     template; skipping the probe silently would let such a deploy report success unverified.
+    //     Only a pure-invoke deployment (no forwarder) legitimately has no URL and nothing to probe.
+    //     `channels.length` is belt-and-braces: the planner derives needsForwarder FROM the channel
+    //     list, but this gate must not silently trust that invariant across callers.
+    if ((plan.needsForwarder || plan.channels.length > 0) && !url) {
+        return gate("this deployment needs the forwarder but the stack has no ForwarderUrl output — regenerate the " +
+            "template with --force");
+    }
+    // 8d. Warm + verify the NEW serving path end to end, BEFORE registration: the probe wakes a fresh
+    //     session on the new image through the forwarder's reserved path, which restores the state
+    //     snapshot and constructs the channels — construction is deferred to exactly that moment
+    //     (channels/agentcore.ts), so this is where a bad credential, a broken channels/ module, or an
+    //     unrestorable snapshot surfaces AT DEPLOY TIME with the runtime's own error text.
+    if (url) {
+        log("probing the deployed runtime (state restore + channel construction)…");
+        const verdict = await probeRuntime(`${url}/__fastagent/probe`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
+        if (!verdict.ok)
+            return gate(verdict.gate);
+        log("runtime verified (state restored, channels constructed)");
+    }
     // 9. Post-deploy webhook registration — same registrar seam as every host, pointed at the
     //    forwarder's Function URL. Gate policy is the shared registration-gate kernel.
-    if (plan.channels.length > 0 && !url) {
-        return gate("channels are declared but the stack has no ForwarderUrl output — regenerate the template with --force");
-    }
     const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
     if (url) {
         if (plan.channels.includes("telegram")) {

package/dist/deploy/preflight.d.ts

@@ -19,9 +19,15 @@ interface DeployFacts {
      *  has no external wake-up, so the deployment must keep one machine running: the fly plan forces
      *  `min_machines_running=1`, the railway runbook forbids App Sleeping. */
     hasTimeTriggers: boolean;
-    /** What satisfies model auth locally ({@link probeAuthSource}) — an env-var name, an OAuth/stored label,
-     *  or undefined. Drives the runbook's secret guidance and `--run`'s credential carry. */
+    /** What satisfies model auth locally — an env-var name, an OAuth/stored label, or undefined. Drives the
+     *  runbook's secret guidance and `--run`'s credential carry. For a models.json endpoint keyed from the
+     *  environment this is the VARIABLE NAME (see {@link modelCredentialCarry}), not the display label, so
+     *  the value carries like any provider key. */
     modelAuth: string | undefined;
+    /** The definition itself carries the model key (a models.json literal `apiKey`, or a `!command` run on
+     *  the host), so there is nothing for `--run` to carry AND nothing to gate: `fastagent login` cannot
+     *  serve a custom provider, so gating on it would strand a correctly configured agent. */
+    modelKeyInDefinition: boolean;
     /** The project-level auth file `--run` reads to carry the credential (probed with the same path). */
     authPath: string;
     /** Container facts shared by the plan and the generated Dockerfile — ONE source, so they can't drift. */

package/dist/deploy/preflight.js

@@ -17,12 +17,13 @@ import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
 import { inspectChannels } from "../engines/pi/channel.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
-import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
+import { isEnvKey } from "./secrets.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
  * matcher (the same library the workspace ignore files use), so `!` negation and last-match-wins are
@@ -126,9 +127,25 @@ export async function preflightDeploy(input) {
         });
     }
     // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
-    // miss a `fastagent login` credential and falsely report "none configured".
+    // miss a `fastagent login` credential and falsely report "none configured". Through the AGENT's model
+    // surface too (its models.json travels into the image), so a custom endpoint is not read as an unknown
+    // provider — this probe feeds the gate that decides whether `--run` may proceed.
     const authPath = resolveAuthPath(agentDir, authPathFlag);
-    const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
+    const models = await createPiModelRuntime({ agentDir, authPath });
+    let modelAuth = modelSpec ? await probeAuthSource(models, modelSpec) : undefined;
+    let modelKeyInDefinition = false;
+    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the
+    // credential REACH the host"). It reports every models.json endpoint as "configured API key" — not an
+    // env-var name — so without this the gate below sees no credential and stops the deploy with two
+    // remedies that are both wrong for such an agent: `fastagent login` cannot serve a custom provider,
+    // and the key is already in the environment.
+    if (modelSpec && !isEnvKey(modelAuth)) {
+        const carry = modelCredentialCarry(models, modelSpec);
+        if (carry.envVar)
+            modelAuth = carry.envVar;
+        else
+            modelKeyInDefinition = carry.inDefinition;
+    }
     // Container facts (shared by every host) + the warnings that follow. The facts describe the AGENT —
     // its package.json/runtime/lockfile drive the image's install step — never the workspace's (the bake
     // ships the whole tree, but the workspace's own manifest belongs to its own deploy).
@@ -195,12 +212,17 @@ export async function preflightDeploy(input) {
         const rel = relative(workspace, p);
         return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
     };
-    // The secrets DIR is the unit, not the two filenames we happen to know: an atomic-write temp beside
-    // auth.json, a second key file, an editor backup of `.env` — all of it must stay out of the image, and
-    // `resolveSecretsDir` says as much ("everything fastagent manages that must never leave the machine").
-    // The auth path adds an entry only when an override puts it OUTSIDE that dir. An external secrets dir
-    // (the deployed posture: a mounted volume) is outside the context — nothing to check, nothing to
-    // exclude.
+    // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below: the
+    // generated ignore excludes the dir's CONTENTS (`**/.secrets/**`) so its two value-free tracked
+    // scaffolds can be re-included, and a directory-level question reads that correct file as "not
+    // excluded" — the generator's own default output gated its own deploy (field-hit: a fresh
+    // kit-layout workspace without --force; --force skips checking our own file, which is why the
+    // combination stayed invisible). What leaks is a FILE, so files are what the gate asks about — see
+    // secretDirFiles below, which enumerates what is actually inside (an atomic-write temp beside
+    // auth.json, a second key file, an editor backup of `.env`: the dir-as-unit worry, covered per
+    // file). The auth path adds an entry only when an override puts it OUTSIDE that dir. An external
+    // secrets dir (the deployed posture: a mounted volume) is outside the context — nothing to check,
+    // nothing to exclude.
     const secretsRel = inContext(resolveSecretsDir(agentDir));
     const authRel = inContext(authPath);
     const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
@@ -246,7 +268,29 @@ export async function preflightDeploy(input) {
             .map((n) => join(relDir, n).split(sep).join("/"));
     };
     const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
-    const leakCandidates = [...(await present(secretPaths)), ...envFiles];
+    // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on
+    // purpose (they carry no values; the generated ignore re-includes them by name). Existence is the
+    // enumeration itself — readdir lists exactly what could be baked — and a hand-written ignore that
+    // misses the dir now gates NAMING the leaking file, a better diagnostic than pointing at a
+    // directory. Recurses: a subdirectory inside .secrets is unusual but its files leak all the same.
+    const secretDirFiles = async (dirRel) => {
+        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name === ".gitignore" || entry.name === ".env.example")
+                continue;
+            if (entry.isDirectory())
+                files.push(...(await secretDirFiles(`${dirRel}/${entry.name}`)));
+            else
+                files.push(`${dirRel}/${entry.name}`);
+        }
+        return files;
+    };
+    const leakCandidates = [
+        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
+        ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
+        ...envFiles,
+    ];
     // Same existence rule: a node_modules that is not there cannot be uploaded.
     const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
     const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];
@@ -383,6 +427,7 @@ export async function preflightDeploy(input) {
         longConnectionChannels,
         hasTimeTriggers,
         modelAuth,
+        modelKeyInDefinition,
         authPath,
         container,
         port,

package/dist/deploy/secrets.d.ts

@@ -38,6 +38,9 @@ export declare function deploymentSecrets(modelAuth: string | undefined, channel
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
+    /** The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is
+     *  no value to carry and no gate to raise — see {@link modelCredentialCarry}. */
+    modelKeyInDefinition?: boolean;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
     longConnectionChannels?: string[];

package/dist/deploy/secrets.js

@@ -65,6 +65,12 @@ export function assembleSecrets(input) {
     else if (input.authFile) {
         secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
     }
+    else if (input.modelKeyInDefinition) {
+        // The definition authenticates itself (models.json literal key, or a command run on the host), so it
+        // travels in the image with everything else. Gating here would be the worst kind of wrong: both
+        // remedies we print are impossible for such an agent — `fastagent login` has no flow for a custom
+        // provider, and there is no provider env key to set.
+    }
     else {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }

package/dist/dev-supervisor.js

@@ -13,7 +13,7 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_NAMES, resolveStateRoot } from "./paths.js";
+import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot } from "./paths.js";
 import { isUnderDir } from "./engines/pi/definition.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
@@ -21,7 +21,7 @@ import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, .secrets/.env";
+const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, models.json, .secrets/.env";
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
  * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
@@ -49,6 +49,12 @@ export function devWatchIgnored(root, envFile) {
             return false;
         if (rel === "package.json")
             return false;
+        // models.json is read ONCE per worker (the model hub is built during assembly), so an edit needs a
+        // restart like any other code input. It is also the one input whose breakage KILLS the worker — a
+        // malformed file fails assembly — so leaving it unwatched would strand the author: the fix that
+        // repairs it would not be the edit that restarts.
+        if (rel === AGENT_MODELS_FILE)
+            return false;
         const segments = rel.split(sep);
         if (segments[0] === "tools" || segments[0] === "channels" || segments[0] === "schedules")
             return false;

package/dist/engines/pi/create.d.ts

@@ -7,7 +7,8 @@ import { type AnyModel, piHarnessFactory } from "./harness.ts";
 import { type PiSessionStore } from "./sessions.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
-import { type Lease, type SessionObserver } from "./invoke.ts";
+import { type SessionObserver } from "./invoke.ts";
+import { type Lease } from "./turn-kit.ts";
 /** pi's core default toolset (read/bash/edit/write). Rooted at the ExecutionEnv's cwd, supplied per
  *  turn as the harness tool context — hence no argument here. */
 export declare function piDefaultTools(): MountedTool[];

package/dist/engines/pi/create.js

@@ -18,12 +18,13 @@ import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition } from "./definition.js";
 import { DEFAULT_THINKING_LEVEL, piHarnessFactory } from "./harness.js";
-import { createPiModels } from "./models.js";
+import { createPiModelRuntime, createPiModels } from "./models.js";
 import { reportFindingsIfChanged } from "./report.js";
 import { inMemorySessionStore } from "./sessions.js";
 import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
 import { withSearchTool } from "./search-tools.js";
-import { createPiAgentFromHarness, inProcessLease } from "./invoke.js";
+import { createPiAgentFromHarness } from "./invoke.js";
+import { inProcessLease } from "./turn-kit.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
 //
 // The full pi toolset is the default for fidelity: authors vibe in local pi with it, so serving with
@@ -164,7 +165,7 @@ export function assembleSystemPrompt(options) {
  * directory) and route through here.
  */
 function buildPiAgent(opts) {
-    const models = createPiModels({ providers: opts.providers, authPath: opts.authPath });
+    const models = opts.models ?? createPiModels({ providers: opts.providers, authPath: opts.authPath });
     const env = opts.env ?? new NodeExecutionEnv({ cwd: process.cwd() });
     // Materialized here (not defaulted inside createPiAgentFromHarness) so the exposed parts carry
     // the SAME lease instance the agent runs under — boundary mutations must contend on it.
@@ -241,13 +242,17 @@ export async function createPiAgentFromDefinition(dir, options) {
     // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied
     // it; a caller's own search_tools wins).
     const tools = withSearchTool(options.tools ?? piDefaultTools());
+    // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
+    // passes an explicit authPath, so this only affects direct L2 callers).
+    const authPath = options.authPath ?? defaultAuthPath(resolveSecretsDir(dir));
     const agent = buildPiAgent({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        providers: options.providers,
-        // Dir-aware default: the same secrets-dir-derived file the opener uses for this dir (the opener
-        // passes an explicit authPath, so this only affects direct L2 callers).
-        authPath: options.authPath ?? defaultAuthPath(resolveSecretsDir(dir)),
+        // THE directory rung's model surface: built-ins + the agent's own models.json (custom endpoints,
+        // which are definition data and travel with the artifact) + any injected Provider instance. This
+        // is what makes `dev`/`start`/`invoke` and an embedded L2 caller resolve the same specs.
+        models: await createPiModelRuntime({ agentDir: dir, authPath, providers: options.providers }),
+        authPath,
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills
         // edits (the author's, or the agent's own self-modification) take effect on the next turn with
         // no process restart — restarts are reserved for code (tools/channels/config, module cache).

package/dist/engines/pi/harness.d.ts

@@ -9,7 +9,7 @@
 import { AgentHarness } from "@earendil-works/pi-agent-core";
 import type { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Model, Models } from "@earendil-works/pi-ai";
-import { type PiSessionStore } from "./sessions.ts";
+import { type PiSessionStore, type SessionInheritance } from "./sessions.ts";
 import { type MountedTool } from "./tool.ts";
 import { type OverrideEntryLike } from "./session-settings.ts";
 /**
@@ -38,7 +38,9 @@ export type AnyModel = Model<any>;
  *  pi's env-backed default tools read (pi 0.83). Custom tools are context-FREE and stay assignable — a
  *  four-parameter `execute` satisfies the five-parameter one, so `defineTool` is untouched by this. */
 type PiHarness = AgentHarness<ExecutionToolContext>;
-export type PiHarnessFactory = (session: string) => PiHarness | Promise<PiHarness>;
+export type PiHarnessFactory = (session: string, 
+/** Where a NEW session starts from (sessions.ts) — an existing session ignores it. */
+inherit?: SessionInheritance) => PiHarness | Promise<PiHarness>;
 export interface PiHarnessFactoryOptions {
     /** Session persistence. Continuity = same backing store + same session id. */
     sessions: PiSessionStore;
@@ -107,6 +109,7 @@ export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], mo
     thinkingLevel: ThinkingLevel;
 };
 export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: MountedTool[], sessionId: string): string[] | undefined;
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
+ *  create, seeded from `inherit` when the scope names a parent. */
 export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;
 export {};

package/dist/engines/pi/harness.js

@@ -114,10 +114,11 @@ export function resolveHarnessActiveToolNames(recorded, tools, sessionId) {
     }
     return [...new Set([...initial, ...known])];
 }
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing →
+ *  create, seeded from `inherit` when the scope names a parent. */
 export function piHarnessFactory(options) {
-    return async (sessionId) => {
-        const session = await options.sessions.openOrCreate(sessionId);
+    return async (sessionId, inherit) => {
+        const session = await options.sessions.openOrCreate(sessionId, inherit);
         // One extra entry walk per invoke to collect the activation deltas — negligible against the model
         // call, same trade as L2's per-invoke definition re-read. The walk is over the ACTIVE PATH, not
         // the flat journal: `navigate` moves the leaf, so the tree can hold an abandoned branch whose

package/dist/engines/pi/invoke-session.d.ts

@@ -0,0 +1,32 @@
+/**
+ * L0 over pi-coding-agent's `AgentSession`, in the `per-invoke` state locality
+ * ([conformance-levels.md](../../../docs/design/conformance-levels.md) §2, top-right cell): build a
+ * session per invoke over the SAME durable jsonl, run one turn, dispose.
+ *
+ * Why this exists next to {@link createPiAgentFromHarness}: pi 0.84 replaced `AgentHarness` with an
+ * unimplemented lane-based skeleton, and pi does not consume that class itself — its TUI, RPC and SDK
+ * all run on `AgentSession`. This is the executable proof that the SPEC's four Agent-side MUSTs hold
+ * on the class pi actually maintains (test/conformance-session.test.ts).
+ *
+ * SCOPE, deliberately narrow: the concurrency floor, the event stream, and cancellation. The
+ * observation plane (SessionObserver / RunControls / the rich `SessionEvent` vocabulary), the tool
+ * activation bridge, auto-compaction and session inheritance are NOT wired.
+ *
+ * WHICH L0 SERVES: {@link createPiAgentFromHarness}, still — this one is reachable only from its
+ * conformance test (deliberately absent from `src/pi.ts`), because a serving path needs the pieces
+ * above. Its one known debt is {@link toAgentEvent}: translating pi events straight to SPEC
+ * `AgentEvent`s is the second parallel translation `docs/design/session-control.md` §6 forbids. It
+ * retires the moment this L0 grows the observation plane — the rich `SessionEvent` layer comes back
+ * with it, and the harness L0 goes away.
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type Agent } from "../../agent.ts";
+import { type Lease } from "./turn-kit.ts";
+/** Open-or-create the session behind `sessionId` and bind an `AgentSession` to it, per invoke. */
+export type PiAgentSessionFactory = (sessionId: string) => Promise<AgentSession>;
+export interface CreatePiAgentFromSessionOptions {
+    sessionFactory: PiAgentSessionFactory;
+    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
+    lease?: Lease;
+}
+export declare function createPiAgentFromSession(options: CreatePiAgentFromSessionOptions): Agent;