stageflow 0.25.0 → 0.30.0

package/dist/agent/cursorProvider.js

@@ -16,12 +16,23 @@ const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
  *
  * Resolution order:
  * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
- * 2. Path package from ~/.pi/agent/settings.json (same source interactive pi uses)
- * 3. npm install under ~/.pi/agent/npm/node_modules/pi-cursor-sdk
+ * 2. Path package from the Pi agent settings.json (same source interactive pi uses)
+ * 3. npm install under <pi-agent>/npm/node_modules/pi-cursor-sdk
  *    (`dist/index.js` for 0.3+, `src/index.ts` for older publishes)
  * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ *
+ * A stage worker's HOME is an empty attempt directory, so the Pi agent dir is
+ * the directory of STAGEFLOW_PI_HOME_AUTH_PATH when the Host set it, not
+ * os.homedir().
  */
 const CURSOR_PACKAGE_ENTRIES = ["dist/index.js", "src/index.ts"];
+/** Pi agent dir. Stage workers must not use os.homedir(): HOME is the attempt dir. */
+function piAgentDir() {
+    const auth = process.env.STAGEFLOW_PI_HOME_AUTH_PATH?.trim();
+    if (auth)
+        return path.dirname(path.resolve(auth));
+    return path.join(os.homedir(), ".pi", "agent");
+}
 export function cursorExtensionEntryInPackage(packageRoot) {
     for (const rel of CURSOR_PACKAGE_ENTRIES) {
         const full = path.join(packageRoot, rel);
@@ -40,7 +51,7 @@ export function resolveCursorExtensionPath() {
     if (fromSettings) {
         return fromSettings;
     }
-    const npmEntry = cursorExtensionEntryInPackage(path.join(os.homedir(), ".pi", "agent", "npm", "node_modules", "pi-cursor-sdk"));
+    const npmEntry = cursorExtensionEntryInPackage(path.join(piAgentDir(), "npm", "node_modules", "pi-cursor-sdk"));
     if (npmEntry) {
         return npmEntry;
     }
@@ -84,6 +95,20 @@ function prepareCursor(modelRef) {
         restore: sealCursorSettingSources(),
     };
 }
+export function workshopCursorBridgeHint(toolNames) {
+    const lines = toolNames.map((name) => `- pi__${name} (playbook name: ${name})`);
+    return [
+        "Cursor bridge: call the workshop tools by these MCP names. The playbook uses the bare names; they are the same tools.",
+        ...lines,
+        "When the operator asks you to create or edit the draft, do not finish without one of these tool calls.",
+    ].join("\n");
+}
+export function cursorBridgePrompt(message, modelId, toolNames) {
+    if (!modelId || !isCursorModelRef(modelId) || toolNames.length === 0) {
+        return message;
+    }
+    return `${message}\n\n${workshopCursorBridgeHint(toolNames)}`;
+}
 export const cursorProviderSupport = {
     id: "cursor",
     matches: isCursorModelRef,
@@ -99,7 +124,8 @@ export const cursorProviderSupport = {
 };
 registerProviderSupport(cursorProviderSupport);
 function resolveFromPiSettings() {
-    const settingsPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    const agentDir = piAgentDir();
+    const settingsPath = path.join(agentDir, "settings.json");
     if (!existsSync(settingsPath)) {
         return undefined;
     }
@@ -113,7 +139,6 @@ function resolveFromPiSettings() {
     if (!Array.isArray(settings.packages)) {
         return undefined;
     }
-    const agentDir = path.join(os.homedir(), ".pi", "agent");
     for (const entry of settings.packages) {
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
             continue;

package/dist/agent/fakeAgent.d.ts

@@ -3,6 +3,7 @@ import type { AgentPort, OpaqueAnswer, OpaqueWaitRequest, StageHandle, StageRunI
 export type FakeAgentBehavior = {
     type: "emit";
     envelope: unknown;
+    toolArgs?: string;
 } | {
     type: "never_emit";
 } | {

package/dist/agent/fakeAgent.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "
 import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
+import { loginCheckIssue } from "../browser/loginCheck.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
@@ -127,6 +128,9 @@ export class FakeAgent {
                 event: "tool_start",
                 toolName: "fake_tool",
                 toolCallId: "fake-1",
+                ...("toolArgs" in behavior && behavior.toolArgs !== undefined
+                    ? { argsPreview: behavior.toolArgs }
+                    : {}),
             });
             input.onActivity?.({
                 event: "tool_end",
@@ -165,6 +169,15 @@ export class FakeAgent {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
+                if (envelope.status !== "failure") {
+                    for (const check of input.stage.pre_emit_checks ?? []) {
+                        if (check.type !== "browser_login_check")
+                            continue;
+                        const issue = loginCheckIssue(envelope.payload, check);
+                        if (issue !== undefined)
+                            throw new Error(issue);
+                    }
+                }
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });
                     return {

package/dist/agent/piAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type EventBus, type InlineExtension, DefaultResourceLoader, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type ExtensionFactory, SessionManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -6,9 +6,18 @@ import { type StageActivityObserver } from "./activityObserver.js";
 import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 import type { StageGateKind } from "../types/stage.js";
 import { type StageUsage } from "../types/usage.js";
+import { STAGEFLOW_PATH_DENIED } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export { createSealedResourceLoader } from "./piSessionFactory.js";
+export declare const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+export declare function createDurableRootPathDenyExtension(options: {
+    runWorkspaceDir: string;
+    durableRoot: string;
+    checkoutRoot?: string;
+}): ExtensionFactory;
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * Includes `ask_operator` only when `gateKinds` is a non-empty list.
  * `write_stage_artifact` when registered (always, for bound and unbound —
  * bound/unbound only gates cwd / env bind).
  */
@@ -67,28 +76,6 @@ export type RouteSessionEventToProgressOptions = {
 export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
 export declare function composeFeedbackResumePrompt(input: StageRunInput): string;
-/**
- * DefaultResourceLoader with host/global discovery turned off.
- *
- * Without these flags the loader walks up from the run folder and would pick
- * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
- * and APPEND_SYSTEM.md. Stages must not inherit that context.
- *
- * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
- * is the isolated MCP seam. With `noExtensions: true`, discovered
- * global/project packages stay out; only those allowlists load.
- * `additionalSkillPaths` is the matching allowlist for one named skill.
- */
-export declare function createSealedResourceLoader(options: {
-    cwd: string;
-    agentDir: string;
-    settingsManager: SettingsManager;
-    systemPrompt: string;
-    additionalExtensionPaths?: string[];
-    additionalSkillPaths?: string[];
-    extensionFactories?: InlineExtension[];
-    eventBus?: EventBus;
-}): DefaultResourceLoader;
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;
 export declare function resolveStageSessionFile(input: StageRunInput): string;

package/dist/agent/piAdapter.js

@@ -26,15 +26,17 @@
  * fails closed with `StageSessionReconstructError` (KTD7). Epic proving
  * vehicle: pipeline `plan-review-proving` (Pi live wait + console answers).
  *
- * `ask_operator` is registered on sealed stage sessions unless the stage
- * declares `gate_kinds: []`.
+ * `ask_operator` is registered on sealed stage sessions only when the stage
+ * declares a non-empty `gate_kinds` list.
  */
 import { existsSync } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { createAgentSession, DefaultResourceLoader, defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { BROWSER_SKILL_NAME } from "../config/builtinSkills.js";
+import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError } from "../config/resolveStageMcpServers.js";
 import { attachIsolatedMcp, STAGEFLOW_PI_MCP_EXTENSION_NAME, } from "./piIsolatedMcp.js";
+import { createPiAgentSession, createSealedResourceLoader, } from "./piSessionFactory.js";
 import { isAdvancingEnvelope } from "../envelope/check.js";
 import { formatFeedbackLoopContext } from "../prompt/feedbackLoopContext.js";
 import { formatPriorEnvelope } from "../prompt/priorEnvelope.js";
@@ -49,9 +51,40 @@ import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { durableRootFileToolDenial, STAGEFLOW_PATH_DENIED, } from "../runstore/workspaceLayout.js";
+export { STAGEFLOW_PATH_DENIED };
+export { createSealedResourceLoader } from "./piSessionFactory.js";
+export const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
+const PATH_DENY_FILE_TOOLS = new Set(["read", "write", "edit"]);
+export function createDurableRootPathDenyExtension(options) {
+    const { runWorkspaceDir, durableRoot, checkoutRoot } = options;
+    const allowlistedRoots = checkoutRoot !== undefined && checkoutRoot !== ""
+        ? [checkoutRoot]
+        : undefined;
+    return (pi) => {
+        pi.on("tool_call", async (event, ctx) => {
+            if (!PATH_DENY_FILE_TOOLS.has(event.toolName)) {
+                return undefined;
+            }
+            const rawPath = event.input.path;
+            if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+                return undefined;
+            }
+            const candidate = path.isAbsolute(rawPath)
+                ? rawPath
+                : path.resolve(ctx.cwd, rawPath);
+            const reason = await durableRootFileToolDenial(candidate, runWorkspaceDir, durableRoot, allowlistedRoots);
+            if (reason !== undefined) {
+                return { block: true, reason };
+            }
+            return undefined;
+        });
+    };
+}
 /**
  * Stage tool allowlist for sealed Pi sessions.
- * Includes `ask_operator` unless `gateKinds` is an empty list (R6).
+ * Includes `ask_operator` only when `gateKinds` is a non-empty list.
  * `write_stage_artifact` when registered (always, for bound and unbound —
  * bound/unbound only gates cwd / env bind).
  */
@@ -63,7 +96,7 @@ export function resolveStageToolNames(emitToolName, artifactToolName, askOperato
         "edit",
         emitToolName,
     ];
-    if (gateKinds === undefined || gateKinds.length > 0) {
+    if (Array.isArray(gateKinds) && gateKinds.length > 0) {
         tools.push(askOperatorToolName);
     }
     if (artifactToolName) {
@@ -416,9 +449,16 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
     }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
-    const skillBaseDir = input.stage.skill !== undefined && input.skillFilePath !== undefined
-        ? path.dirname(input.skillFilePath)
-        : undefined;
+    const skillBaseDirs = [
+        input.stage.skill !== undefined && input.skillFilePath !== undefined
+            ? path.dirname(input.skillFilePath)
+            : undefined,
+        input.browserSkillFilePath !== undefined
+            ? path.dirname(input.browserSkillFilePath)
+            : undefined,
+    ].filter((dir) => dir !== undefined);
+    const skillBaseDir = skillBaseDirs.length > 0 ? skillBaseDirs.join(", ") : undefined;
+    const browserGuidance = formatBrowserGuidance(input);
     const artifactGuidance = input.roots.mode === "bound" && artifactToolName !== undefined
         ? [
             `Project checkout (agent cwd): ${input.roots.checkoutRoot}`,
@@ -453,16 +493,38 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             : "",
         "",
         artifactGuidance,
+        browserGuidance,
         emitHint,
     ]
         .filter(Boolean)
         .join("\n");
 }
+function formatBrowserGuidance(input) {
+    const browser = input.stage.browser;
+    if (browser === undefined)
+        return "";
+    const lines = [
+        "This stage has a browser. Run only agent-browser commands in bash. The session is already set in the environment.",
+    ];
+    if (browser.allow_domains !== undefined && browser.allow_domains.length > 0) {
+        lines.push(`Allowed domains: ${browser.allow_domains.join(", ")}. Open no other domain.`);
+    }
+    if (input.browserSkillFilePath !== undefined &&
+        input.stage.skill !== BROWSER_SKILL_NAME) {
+        lines.push(input.stage.skill !== undefined
+            ? `Before you use the browser, read the browser skill at ${input.browserSkillFilePath}.`
+            : "Follow the browser skill.");
+    }
+    return lines.join("\n");
+}
 export function composeStageUserPrompt(input, emitToolName, emitHintOverride, artifactToolName) {
     const body = buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName);
     if (input.stage.skill !== undefined) {
         return `/skill:${input.stage.skill} ${body}`;
     }
+    if (input.browserSkillFilePath !== undefined && input.stage.browser !== undefined) {
+        return `/skill:${BROWSER_SKILL_NAME} ${body}`;
+    }
     return body;
 }
 export function composeFeedbackResumePrompt(input) {
@@ -475,38 +537,6 @@ export function composeFeedbackResumePrompt(input) {
         formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode ?? "feedback_resume"),
     ].join("\n\n");
 }
-/**
- * DefaultResourceLoader with host/global discovery turned off.
- *
- * Without these flags the loader walks up from the run folder and would pick
- * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
- * and APPEND_SYSTEM.md. Stages must not inherit that context.
- *
- * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
- * is the isolated MCP seam. With `noExtensions: true`, discovered
- * global/project packages stay out; only those allowlists load.
- * `additionalSkillPaths` is the matching allowlist for one named skill.
- */
-export function createSealedResourceLoader(options) {
-    return new DefaultResourceLoader({
-        cwd: options.cwd,
-        agentDir: options.agentDir,
-        settingsManager: options.settingsManager,
-        systemPromptOverride: () => options.systemPrompt,
-        appendSystemPromptOverride: () => [],
-        additionalExtensionPaths: options.additionalExtensionPaths,
-        additionalSkillPaths: options.additionalSkillPaths,
-        ...(options.extensionFactories !== undefined
-            ? { extensionFactories: options.extensionFactories }
-            : {}),
-        ...(options.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
-        noContextFiles: true,
-        noExtensions: true,
-        noSkills: true,
-        noPromptTemplates: true,
-        noThemes: true,
-    });
-}
 function collectMcpExtensionToolNames(loader) {
     const inlinePath = `<inline:${STAGEFLOW_PI_MCP_EXTENSION_NAME}>`;
     const names = [];
@@ -773,11 +803,11 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     }, input.feedbackLoopEmitContext);
     const emitTool = defineTool(emitDef);
     const gateKinds = input.stage.gate_kinds;
-    const includeAsk = gateKinds === undefined || gateKinds.length > 0;
+    const includeAsk = Array.isArray(gateKinds) && gateKinds.length > 0;
     const askDef = includeAsk
         ? createAskOperatorTool({
             requestWait: (prompt) => askWaitChannel.requestWait(prompt),
-            ...(gateKinds !== undefined ? { allowedKinds: gateKinds } : {}),
+            allowedKinds: gateKinds,
         })
         : undefined;
     const askTool = askDef ? defineTool(askDef) : undefined;
@@ -793,6 +823,10 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             reason: `Skill "${input.stage.skill}" is not installed`,
         };
     }
+    const additionalSkillPaths = [
+        input.skillFilePath,
+        input.stage.browser !== undefined ? input.browserSkillFilePath : undefined,
+    ].filter((p, i, all) => p !== undefined && all.indexOf(p) === i);
     const additionalExtensionPaths = [];
     let restoreProvider;
     if (provider) {
@@ -825,18 +859,27 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             restoreProvider?.();
             return { ok: false, reason };
         };
+        const extensionFactories = [
+            {
+                name: STAGEFLOW_PATH_DENY_EXTENSION_NAME,
+                factory: createDurableRootPathDenyExtension({
+                    runWorkspaceDir: roots.runWorkspaceDir,
+                    durableRoot: globalStageflowHome(),
+                    ...(roots.checkoutRoot !== undefined
+                        ? { checkoutRoot: roots.checkoutRoot }
+                        : {}),
+                }),
+            },
+            ...(attached.extensionFactories ?? []),
+        ];
         const loader = createSealedResourceLoader({
             cwd: roots.cwd,
             agentDir: roots.agentDir,
             settingsManager,
             systemPrompt: input.stage.system_prompt,
             additionalExtensionPaths,
-            ...(input.skillFilePath !== undefined
-                ? { additionalSkillPaths: [input.skillFilePath] }
-                : {}),
-            ...(attached.extensionFactories !== undefined
-                ? { extensionFactories: attached.extensionFactories }
-                : {}),
+            ...(additionalSkillPaths.length > 0 ? { additionalSkillPaths } : {}),
+            extensionFactories,
             ...(attached.eventBus !== undefined ? { eventBus: attached.eventBus } : {}),
         });
         await loader.reload();
@@ -917,7 +960,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
     }
     let session;
     try {
-        const created = await createAgentSession({
+        const created = await createPiAgentSession({
             cwd: input.roots.cwd,
             agentDir: input.roots.agentDir,
             modelRuntime: wiring.modelRuntime,
@@ -943,6 +986,13 @@ export async function reconstructStageSessionForAnswer(input, answer) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
         const liveSession = session;
         return {
             session: liveSession,
@@ -969,7 +1019,7 @@ export async function reconstructStageSessionForAnswer(input, answer) {
 }
 async function bindStageSession(input, sessionManager, wiring) {
     const { roots } = input;
-    const created = await createAgentSession({
+    const created = await createPiAgentSession({
         cwd: roots.cwd,
         agentDir: roots.agentDir,
         modelRuntime: wiring.modelRuntime,
@@ -1011,6 +1061,13 @@ async function bindStageSession(input, sessionManager, wiring) {
         if (resolved.thinkingLevel) {
             session.setThinkingLevel(resolved.thinkingLevel);
         }
+        await input.onResolvedModel?.({
+            stageId: runtimeStageId(input),
+            model: resolved.model.id,
+            ...(resolved.thinkingLevel !== undefined
+                ? { thinkingLevel: resolved.thinkingLevel }
+                : {}),
+        });
     }
     catch (err) {
         await shutdownSession(session);

package/dist/agent/piIsolatedMcp.d.ts

@@ -1,6 +1,8 @@
 import { type EventBus, type InlineExtension } from "@earendil-works/pi-coding-agent";
 import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 export declare const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
+export declare function jitiFsCacheDir(): string;
+export declare function resetCreateMcpAdapterCacheForTests(): void;
 type IsolatedMcpServerEntry = Record<string, unknown> & {
     lifecycle: "lazy" | "eager";
     directTools: true;

package/dist/agent/piIsolatedMcp.js

@@ -1,10 +1,18 @@
+import path from "node:path";
 import { createEventBus, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError, } from "../config/resolveStageMcpServers.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 export const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
 const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
-const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 5_000;
+const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 30_000;
 const STATUS_POLL_MS = 50;
 const PI_MCP_ADAPTER_SPEC = "pi-mcp-adapter";
+export function jitiFsCacheDir() {
+    return path.join(globalStageflowHome(), "cache", "jiti");
+}
+export function resetCreateMcpAdapterCacheForTests() {
+    cachedCreateMcpAdapter = undefined;
+}
 const ISOLATED_MCP_SETTINGS = {
     directTools: true,
     elicitation: false,
@@ -58,7 +66,7 @@ async function loadCreateMcpAdapter() {
         // Node does not type-strip .ts under node_modules.
     }
     const { createJiti } = await import("jiti/static");
-    const jiti = createJiti(import.meta.url);
+    const jiti = createJiti(import.meta.url, { fsCache: jitiFsCacheDir() });
     const mod = (await jiti.import(PI_MCP_ADAPTER_SPEC));
     cachedCreateMcpAdapter = mod.createMcpAdapter;
     return cachedCreateMcpAdapter;

package/dist/agent/piSessionFactory.d.ts

@@ -0,0 +1,38 @@
+import { type CreateAgentSessionResult, type EventBus, type InlineExtension, type ToolDefinition, DefaultResourceLoader, type ModelRuntime, type SessionManager, type SettingsManager } from "@earendil-works/pi-coding-agent";
+export declare const WORKSHOP_FORBIDDEN_BUILTIN_TOOLS: readonly ["bash", "write", "edit"];
+export type SealedResourceLoaderOptions = {
+    cwd: string;
+    agentDir: string;
+    settingsManager: SettingsManager;
+    systemPrompt: string;
+    additionalExtensionPaths?: string[];
+    additionalSkillPaths?: string[];
+    extensionFactories?: InlineExtension[];
+    eventBus?: EventBus;
+};
+/**
+ * DefaultResourceLoader with host/global discovery turned off.
+ *
+ * Without these flags the loader walks up from the run folder and would pick
+ * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
+ * and APPEND_SYSTEM.md. Stages must not inherit that context.
+ *
+ * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
+ * is the isolated MCP seam. With `noExtensions: true`, discovered
+ * global/project packages stay out; only those allowlists load.
+ * `additionalSkillPaths` is the matching allowlist for one named skill.
+ */
+export declare function createSealedResourceLoader(options: SealedResourceLoaderOptions): DefaultResourceLoader;
+export type CreatePiAgentSessionOptions = {
+    cwd: string;
+    agentDir: string;
+    modelRuntime: ModelRuntime;
+    sessionManager: SessionManager;
+    customTools?: ToolDefinition[];
+    tools?: string[];
+    settingsManager?: SettingsManager;
+    resourceLoader: DefaultResourceLoader;
+};
+export declare function createPiAgentSession(options: CreatePiAgentSessionOptions): Promise<CreateAgentSessionResult>;
+export declare function assertWorkshopToolsExcludeDiskShell(tools: readonly string[]): void;
+export declare function resolveWorkshopToolNames(customToolNames: string[]): string[];

package/dist/agent/piSessionFactory.js

@@ -0,0 +1,60 @@
+import { createAgentSession, DefaultResourceLoader, } from "@earendil-works/pi-coding-agent";
+export const WORKSHOP_FORBIDDEN_BUILTIN_TOOLS = ["bash", "write", "edit"];
+/**
+ * DefaultResourceLoader with host/global discovery turned off.
+ *
+ * Without these flags the loader walks up from the run folder and would pick
+ * up the consumer project's AGENTS.md, `.agents/skills/`, `.pi/extensions`,
+ * and APPEND_SYSTEM.md. Stages must not inherit that context.
+ *
+ * `additionalExtensionPaths` is the Cursor/provider seam. `extensionFactories`
+ * is the isolated MCP seam. With `noExtensions: true`, discovered
+ * global/project packages stay out; only those allowlists load.
+ * `additionalSkillPaths` is the matching allowlist for one named skill.
+ */
+export function createSealedResourceLoader(options) {
+    return new DefaultResourceLoader({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        settingsManager: options.settingsManager,
+        systemPromptOverride: () => options.systemPrompt,
+        appendSystemPromptOverride: () => [],
+        additionalExtensionPaths: options.additionalExtensionPaths,
+        additionalSkillPaths: options.additionalSkillPaths,
+        ...(options.extensionFactories !== undefined
+            ? { extensionFactories: options.extensionFactories }
+            : {}),
+        ...(options.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
+        noContextFiles: true,
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+    });
+}
+export async function createPiAgentSession(options) {
+    return createAgentSession({
+        cwd: options.cwd,
+        agentDir: options.agentDir,
+        modelRuntime: options.modelRuntime,
+        ...(options.tools !== undefined ? { tools: options.tools } : {}),
+        ...(options.customTools !== undefined
+            ? { customTools: options.customTools }
+            : {}),
+        resourceLoader: options.resourceLoader,
+        sessionManager: options.sessionManager,
+        ...(options.settingsManager !== undefined
+            ? { settingsManager: options.settingsManager }
+            : {}),
+    });
+}
+export function assertWorkshopToolsExcludeDiskShell(tools) {
+    const forbidden = WORKSHOP_FORBIDDEN_BUILTIN_TOOLS.filter((name) => tools.includes(name));
+    if (forbidden.length > 0) {
+        throw new Error(`Workshop Pi allowlist must not include disk/shell builtins: ${forbidden.join(", ")}`);
+    }
+}
+export function resolveWorkshopToolNames(customToolNames) {
+    assertWorkshopToolsExcludeDiskShell(customToolNames);
+    return [...customToolNames];
+}

package/dist/agent/port.d.ts

@@ -63,6 +63,8 @@ export type StageRunInput = {
     /** Optional raw assistant-text-delta sink, fired alongside onActivity, not instead of it. */
     onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
+    /** Bundled browser skill; set by the runtime when the stage has `browser`. */
+    browserSkillFilePath?: string;
     forkEmitContext?: ForkEmitContext;
     cloneEmitContext?: CloneEmitContext;
     /** Declared source policy; successful emits must continue or send work back. */
@@ -75,6 +77,12 @@ export type StageRunInput = {
     repairContext?: StageRepairContext;
     /** Live attempt-scoped QA trail; read at emit execute time, not bootstrap time. */
     readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
+    /** Optional: record the provider-resolved model after resolveCliModel. */
+    onResolvedModel?: (info: {
+        stageId: string;
+        model: string;
+        thinkingLevel?: string;
+    }) => void | Promise<void>;
 };
 export declare function runtimeStageId(input: Pick<StageRunInput, "stage" | "stageId">): string;
 export type StageRunResult = {

package/dist/agent/streamLogRedact.d.ts

@@ -1,2 +1,8 @@
-/** Scrub common secret-shaped substrings before text is persisted or returned. */
+/** Scrub secret-shaped substrings and registered values before text is persisted. */
 export declare function redactSecrets(text: string): string;
+/** Like redactSecrets plus cookie/storage/header shapes; for browser stages only. */
+export declare function redactBrowserSecrets(text: string): string;
+/** Tool/message previews of browser stages can carry cookie or token values. */
+export declare function redactBrowserActivityEvent<T extends {
+    event: string;
+}>(event: T): T;

package/dist/agent/streamLogRedact.js

@@ -1,13 +1,28 @@
-const SECRET_PATTERNS = [
-    /\bsk-[A-Za-z0-9_-]{16,}\b/g,
-    /\bghp_[A-Za-z0-9]{20,}\b/g,
-    /\b[A-Za-z_]*KEY[A-Za-z_]*\s*[:=]\s*['"]?[A-Za-z0-9+/_-]{16,}['"]?/gi,
-];
-/** Scrub common secret-shaped substrings before text is persisted or returned. */
+import { BROWSER_STAGE_PATTERNS, redact, redactString, } from "../logging/redact.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
+/** Scrub secret-shaped substrings and registered values before text is persisted. */
 export function redactSecrets(text) {
-    let out = text;
-    for (const pattern of SECRET_PATTERNS) {
-        out = out.replace(pattern, "[redacted]");
-    }
-    return out;
+    return redactString(text, { namedSecrets: getNamedSecrets() });
+}
+/** Like redactSecrets plus cookie/storage/header shapes; for browser stages only. */
+export function redactBrowserSecrets(text) {
+    return redactString(text, {
+        patterns: BROWSER_STAGE_PATTERNS,
+        namedSecrets: getNamedSecrets(),
+    });
+}
+const BROWSER_REDACTED_EVENTS = new Set([
+    "message",
+    "tool_start",
+    "tool_end",
+    "tool_progress",
+]);
+/** Tool/message previews of browser stages can carry cookie or token values. */
+export function redactBrowserActivityEvent(event) {
+    if (!BROWSER_REDACTED_EVENTS.has(event.event))
+        return event;
+    return redact(event, {
+        patterns: BROWSER_STAGE_PATTERNS,
+        namedSecrets: getNamedSecrets(),
+    });
 }