@peakflo/agent-harness 0.2.3 → 0.2.4-rc.2

package/dist/adapters/coding-agent-adapter.d.ts

@@ -42,6 +42,14 @@ export interface SessionConfig {
     agentId: string;
     taskId: string;
     workspaceDir: string;
+    /**
+     * Refuse dev servers and app scaffolding in shell calls unless the turn's
+     * own message asks for an app. Absent means the control plane did not say,
+     * which keeps the previous behaviour.
+     */
+    devServerPolicy?: {
+        blockDevServers: boolean;
+    };
     serverUrl?: string;
     model?: string;
     reasoningEffort?: ReasoningEffort;

package/dist/adapters/pi-adapter.d.ts

@@ -6,6 +6,7 @@
  */
 import type { CodingAgentAdapter, MessagePart, SessionConfig, SessionMessage, SessionStatus } from './coding-agent-adapter';
 import { type ModelGatewayConfigSource } from './model-gateway';
+export declare const PI_DEV_SERVER_POLICY_ENV = "PF_DEV_SERVER_POLICY_FILE";
 /**
  * Most model providers cap function/tool `name` at 64 characters. Pi forwards
  * MCP tools as `<server>_<tool>`-style names, so a long MCP server name (e.g.
@@ -43,6 +44,7 @@ export declare function withProviderNameLimitHint(error: string): string;
  * characters, before the model can call a tool.
  */
 export declare function buildPiMcpConfigDocument(servers: NonNullable<SessionConfig['mcpServers']>, onRename?: (name: string, slug: string) => void): Record<string, unknown>;
+export declare const PI_PERMISSION_EXTENSION_SOURCE: string;
 export declare class PiAdapter implements CodingAgentAdapter {
     private modelGateway;
     private sessions;
@@ -96,7 +98,7 @@ export declare class PiAdapter implements CodingAgentAdapter {
     private handleToolEvent;
     private command;
     private sendRecord;
-    sendPrompt(sessionId: string, parts: MessagePart[], _config: SessionConfig): Promise<void>;
+    sendPrompt(sessionId: string, parts: MessagePart[], config: SessionConfig): Promise<void>;
     /**
      * THE LONG-TURNS SOFT WARNING'S DELIVERY MECHANISM.
      *

package/dist/adapters/pi-adapter.js

@@ -6,7 +6,7 @@
  * process per live turn and converts Pi events to the shared adapter shape.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PiAdapter = exports.PI_MCP_SERVER_ALIASES = exports.MAX_PI_MCP_SERVER_SLUG_LENGTH = exports.MAX_PI_NAME_LENGTH = void 0;
+exports.PiAdapter = exports.PI_PERMISSION_EXTENSION_SOURCE = exports.PI_MCP_SERVER_ALIASES = exports.MAX_PI_MCP_SERVER_SLUG_LENGTH = exports.MAX_PI_NAME_LENGTH = exports.PI_DEV_SERVER_POLICY_ENV = void 0;
 exports.findPiNodeRuntime = findPiNodeRuntime;
 exports.sanitizePiSessionName = sanitizePiSessionName;
 exports.sanitizePiMcpServerName = sanitizePiMcpServerName;
@@ -21,11 +21,13 @@ const string_decoder_1 = require("string_decoder");
 const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const model_gateway_1 = require("./model-gateway");
+const dev_server_guard_1 = require("../runtime/dev-server-guard");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const RPC_TIMEOUT_MS = 15_000;
 const MAX_BUFFERED_PARTS = 1_000;
 const MINIMUM_PI_VERSION = [0, 80, 5];
 const PI_PERMISSION_MODE_ENV = 'PEAKFLO_PI_PERMISSION_MODE';
+exports.PI_DEV_SERVER_POLICY_ENV = 'PF_DEV_SERVER_POLICY_FILE';
 const TERMINAL_ERROR_SETTLE_GRACE_MS = 1_000;
 const piInstanceIdCache = new Map();
 /**
@@ -163,11 +165,30 @@ function buildPiMcpConfigDocument(servers, onRename) {
         mcpServers
     };
 }
-const PI_PERMISSION_EXTENSION_SOURCE = `\
+exports.PI_PERMISSION_EXTENSION_SOURCE = `\
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
 
 const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]);
 
+/*
+ * The dev-server guard. The matcher is embedded from the harness source, so
+ * the refusal and the matcher cannot drift apart. The per-turn decision comes
+ * from the policy file the harness writes before each prompt (fail open when
+ * the file is absent: a session without a policy is unchanged).
+ */
+${dev_server_guard_1.devServerCommandKind.toString()}
+
+function devServerBlockForTurn(): boolean {
+  try {
+    const path = process.env.PF_DEV_SERVER_POLICY_FILE;
+    if (!path) return false;
+    return JSON.parse(readFileSync(path, "utf8")).block === true;
+  } catch {
+    return false;
+  }
+}
+
 function inputSummary(input: unknown): string {
   try {
     return JSON.stringify(input, null, 2).slice(0, 4000);
@@ -178,6 +199,14 @@ function inputSummary(input: unknown): string {
 
 export default function permissions(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
+    const command = (event.input as { command?: unknown } | undefined)?.command;
+    if (typeof command === "string" && devServerBlockForTurn()) {
+      const kind = devServerCommandKind(command);
+      if (kind) {
+        console.warn(\`[pf-dev-server-guard] refused \${kind}: \${command.slice(0, 200)}\`);
+        return { block: true, reason: ${JSON.stringify(dev_server_guard_1.DEV_SERVER_REFUSAL)} };
+      }
+    }
     if (process.env.${PI_PERMISSION_MODE_ENV} === "allow" || READ_ONLY_TOOLS.has(event.toolName)) return;
     const approved = await ctx.ui.confirm(
       \`Allow \${event.toolName}?\`,
@@ -351,9 +380,9 @@ class PiAdapter {
         const path = (0, path_1.join)(dir, 'permissions.ts');
         (0, fs_1.mkdirSync)(dir, { recursive: true });
         const current = (0, fs_1.existsSync)(path) ? (0, fs_1.readFileSync)(path, 'utf8') : '';
-        if (current !== PI_PERMISSION_EXTENSION_SOURCE) {
+        if (current !== exports.PI_PERMISSION_EXTENSION_SOURCE) {
             const temporaryPath = `${path}.${process.pid}.tmp`;
-            (0, fs_1.writeFileSync)(temporaryPath, PI_PERMISSION_EXTENSION_SOURCE, {
+            (0, fs_1.writeFileSync)(temporaryPath, exports.PI_PERMISSION_EXTENSION_SOURCE, {
                 mode: 0o600
             });
             (0, fs_1.chmodSync)(temporaryPath, 0o600);
@@ -510,7 +539,17 @@ class PiAdapter {
             args.push('--mcp-config', mcpConfigPath);
         for (const skillPath of skills.paths)
             args.push('--skill', skillPath);
-        const invocation = this.piInvocation(executable, args, this.processEnv(config, gateway));
+        // One policy file per Pi process. The harness rewrites it before every
+        // prompt; the extension reads it on every shell call.
+        const devServerPolicyPath = (0, path_1.join)((0, os_1.homedir)(), '.pf-agent-harness', 'pi', 'policy', `${(0, crypto_1.randomUUID)()}.json`);
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(devServerPolicyPath), { recursive: true });
+        (0, fs_1.writeFileSync)(devServerPolicyPath, JSON.stringify({ block: false }), {
+            mode: 0o600
+        });
+        const invocation = this.piInvocation(executable, args, {
+            ...this.processEnv(config, gateway),
+            [exports.PI_DEV_SERVER_POLICY_ENV]: devServerPolicyPath
+        });
         const child = (0, child_process_1.spawn)(invocation.command, invocation.args, {
             cwd: config.workspaceDir,
             env: invocation.env,
@@ -521,6 +560,7 @@ class PiAdapter {
         });
         const tempId = resumeId || (0, crypto_1.randomUUID)();
         const session = this.createSessionState(tempId, child, config, mcpConfigPath, skills.directory);
+        session.devServerPolicyPath = devServerPolicyPath;
         this.sessions.set(tempId, session);
         this.attachProcess(session);
         try {
@@ -989,7 +1029,7 @@ class PiAdapter {
             this.onDataAvailable?.(session.id);
         });
     }
-    async sendPrompt(sessionId, parts, _config) {
+    async sendPrompt(sessionId, parts, config) {
         const session = this.sessions.get(sessionId);
         if (!session)
             throw new Error(`Session not found: ${sessionId}`);
@@ -999,6 +1039,12 @@ class PiAdapter {
             .join('\n');
         if (!message)
             throw new Error('No text content in prompt parts');
+        // Decided per turn from the user's own words, then read by the extension.
+        if (session.devServerPolicyPath) {
+            (0, fs_1.writeFileSync)(session.devServerPolicyPath, JSON.stringify({
+                block: (0, dev_server_guard_1.turnBlocksDevServers)(config.devServerPolicy, message)
+            }), { mode: 0o600 });
+        }
         const wasBusy = session.status === 'busy';
         session.status = 'busy';
         session.lastError = null;

package/dist/capabilities.d.ts

@@ -24,6 +24,14 @@
  *    every heartbeat rather than trusting the registration snapshot.
  */
 import { RunnerCapabilities } from './types';
+/**
+ * What this harness build can do beyond the baseline. The control plane reads
+ * these to decide what to send: a feature missing here is never sent to.
+ *
+ * - `spaceFiles`: syncs `space-files/` (read-only) and serves
+ *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ */
+export declare const HARNESS_FEATURES: readonly ["spaceFiles"];
 export interface ProbeResult {
     installed: boolean;
     version: string | null;

package/dist/capabilities.js

@@ -25,6 +25,7 @@
  *    every heartbeat rather than trusting the registration snapshot.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARNESS_FEATURES = void 0;
 exports.probe = probe;
 exports.probeCapabilities = probeCapabilities;
 const node_child_process_1 = require("node:child_process");
@@ -33,6 +34,14 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const version_1 = require("./version");
 const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * What this harness build can do beyond the baseline. The control plane reads
+ * these to decide what to send: a feature missing here is never sent to.
+ *
+ * - `spaceFiles`: syncs `space-files/` (read-only) and serves
+ *   `knowledge_files_list` / `knowledge_file_download` (P9).
+ */
+exports.HARNESS_FEATURES = ['spaceFiles'];
 /**
  * The coding-agent backends this harness knows how to drive, and the command
  * that reports each one's version.
@@ -156,6 +165,7 @@ async function probeCapabilities(options = {}) {
         git: git.installed,
         docker: docker.installed,
         maxConcurrentSessions: options.maxConcurrentSessions ?? 1,
+        features: [...exports.HARNESS_FEATURES],
         labels: options.labels
     };
 }

package/dist/contract.d.ts

@@ -194,6 +194,10 @@ export declare const ROUTES: {
     readonly lease: (runnerId: string, waitSeconds?: number, protocolVersion?: number) => string;
     /** Bearer: runner credential. Visibility-timeout renewal. */
     readonly leaseRenew: (runnerId: string, leaseId: string) => string;
+    /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
+    readonly knowledgeFiles: (runnerId: string, leaseId: string) => string;
+    /** Bearer: runner credential. A short-lived download URL for one knowledge file. */
+    readonly knowledgeDownload: (runnerId: string, leaseId: string) => string;
     /**
      * Bearer: runner credential. THE RUNTIME-NEUTRAL ROUTE — a Daytona sandbox,
      * a customer VM and the 20x desktop all call this identical path.

package/dist/contract.js

@@ -234,6 +234,10 @@ exports.ROUTES = {
     },
     /** Bearer: runner credential. Visibility-timeout renewal. */
     leaseRenew: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/renew`,
+    /** Bearer: runner credential. Metadata of the knowledge files this turn may read. */
+    knowledgeFiles: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/knowledge/files`,
+    /** Bearer: runner credential. A short-lived download URL for one knowledge file. */
+    knowledgeDownload: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/knowledge/download`,
     /**
      * Bearer: runner credential. THE RUNTIME-NEUTRAL ROUTE — a Daytona sandbox,
      * a customer VM and the 20x desktop all call this identical path.

package/dist/control-plane.d.ts

@@ -1,4 +1,4 @@
-import { ControlPlaneErrorBody, CredentialRotateResponse, DeregisterResponse, IngestRequest, IngestResponse, LeaseRenewResponse, LeaseResponse, RunnerCapabilities, RunnerHeartbeatResponse, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionHistoryResponse } from './types';
+import { ControlPlaneErrorBody, CredentialRotateResponse, DeregisterResponse, IngestRequest, IngestResponse, KnowledgeDownloadResponse, KnowledgeFilesResponse, LeaseRenewResponse, LeaseResponse, RunnerCapabilities, RunnerHeartbeatResponse, RunnerRegisterResponse, RunnerRuntime, RunnerStatus, SessionHistoryResponse } from './types';
 export declare class ControlPlaneError extends Error {
     readonly status: number;
     /** The stable machine-readable code from the body, when the server sent one. */
@@ -130,6 +130,13 @@ export declare class ControlPlaneClient {
      */
     lease(waitSeconds?: number): Promise<LeaseResponse | null>;
     renewLease(leaseId: string, status?: RunnerStatus, githubTokenExpiresAt?: string, modelTokenExpiresAt?: string): Promise<LeaseRenewResponse>;
+    /** Metadata of the knowledge files the lease's turn may read. Never a URL. */
+    knowledgeFiles(leaseId: string, datastoreId?: string): Promise<KnowledgeFilesResponse>;
+    /**
+     * A short-lived signed URL for one knowledge file, for the harness to fetch.
+     * The caller must not log the response's `url`.
+     */
+    knowledgeDownload(leaseId: string, datastoreId: string, fileId: string): Promise<KnowledgeDownloadResponse>;
     /**
      * THE RUNTIME-NEUTRAL ROUTE. A Daytona sandbox, a customer VM and the 20x
      * desktop all call exactly this.

package/dist/control-plane.js

@@ -263,6 +263,32 @@ class ControlPlaneClient {
         });
     }
     /* ------------------------------------------------------------------ */
+    /* 4b. knowledge files (P9)                                            */
+    /* ------------------------------------------------------------------ */
+    /** Metadata of the knowledge files the lease's turn may read. Never a URL. */
+    async knowledgeFiles(leaseId, datastoreId) {
+        const runnerId = this.requireRunnerId();
+        return this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.knowledgeFiles(runnerId, leaseId),
+            token: this.requireCredential(),
+            body: { protocolVersion: contract_1.PROTOCOL_VERSION, datastoreId }
+        });
+    }
+    /**
+     * A short-lived signed URL for one knowledge file, for the harness to fetch.
+     * The caller must not log the response's `url`.
+     */
+    async knowledgeDownload(leaseId, datastoreId, fileId) {
+        const runnerId = this.requireRunnerId();
+        return this.send({
+            method: 'POST',
+            path: contract_1.ROUTES.knowledgeDownload(runnerId, leaseId),
+            token: this.requireCredential(),
+            body: { protocolVersion: contract_1.PROTOCOL_VERSION, datastoreId, fileId }
+        });
+    }
+    /* ------------------------------------------------------------------ */
     /* 5. ingest                                                           */
     /* ------------------------------------------------------------------ */
     /**

package/dist/harness.d.ts

@@ -119,6 +119,8 @@ export declare class Harness {
     private readonly client;
     private readonly health;
     private readonly proxy;
+    /** One loopback host for every session this process runs (P9 knowledge tools). */
+    private readonly knowledgeHost;
     private readonly store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
     private readonly conversation;

package/dist/harness.js

@@ -12,6 +12,7 @@ const github_workspace_1 = require("./github-workspace");
 const health_1 = require("./health");
 const model_probe_1 = require("./model-probe");
 const ports_default_1 = require("./ports-default");
+const knowledge_tools_1 = require("./runtime/knowledge-tools");
 const lease_renewal_1 = require("./runtime/lease-renewal");
 const mcp_auth_proxy_1 = require("./runtime/mcp-auth-proxy");
 const session_runner_1 = require("./runtime/session-runner");
@@ -94,6 +95,8 @@ class Harness {
     client;
     health;
     proxy;
+    /** One loopback host for every session this process runs (P9 knowledge tools). */
+    knowledgeHost = new knowledge_tools_1.KnowledgeToolHost({ logger: console });
     store;
     /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
     conversation;
@@ -1293,6 +1296,13 @@ class Harness {
             store: this.store,
             workspace: this.workspace,
             proxy: this.proxy,
+            knowledge: {
+                host: this.knowledgeHost,
+                control: {
+                    list: (datastoreId) => this.client.knowledgeFiles(lease.leaseId, datastoreId),
+                    download: (datastoreId, fileId) => this.client.knowledgeDownload(lease.leaseId, datastoreId, fileId)
+                }
+            },
             secrets: this.secrets,
             events: this.events,
             telemetry: this.telemetry,

package/dist/runtime/attachments.d.ts

@@ -60,6 +60,12 @@ export declare function sanitizeAttachmentMimeType(raw: unknown): string;
  * the id's own shape.
  */
 export declare function turnToken(turnId: string): string;
+/**
+ * Add one pattern to a repository workspace's local exclude file. Shared by
+ * attachments and Space files (P9): both are mirrors of stored bytes that an
+ * agent must not commit by accident.
+ */
+export declare function excludePatternFromGit(workspaceDir: string, pattern: string, logger: Pick<Console, 'warn'>): Promise<void>;
 /**
  * Download every attachment into `<workspaceDir>/attachments/`.
  *

package/dist/runtime/attachments.js

@@ -4,6 +4,7 @@ exports.ATTACHMENT_DOWNLOAD_TIMEOUT_MS = exports.MAX_ATTACHMENT_BYTES = exports.
 exports.sanitizeAttachmentName = sanitizeAttachmentName;
 exports.sanitizeAttachmentMimeType = sanitizeAttachmentMimeType;
 exports.turnToken = turnToken;
+exports.excludePatternFromGit = excludePatternFromGit;
 exports.syncAttachmentsToWorkspace = syncAttachmentsToWorkspace;
 exports.attachmentPromptNote = attachmentPromptNote;
 /**
@@ -192,25 +193,15 @@ async function resolveGitDir(workspaceDir) {
     }
 }
 /**
- * Best-effort: keep `attachments/` out of `git status` in a repository-mode
- * workspace, so an agent that stages "everything that changed" cannot commit
- * a user's uploaded file into the repository it is working on.
- *
- * Written to `<gitdir>/info/exclude`, NOT `.gitignore` — the former is local
- * to this checkout and is never itself a tracked file the agent could commit
- * or a diff it could see, which matters because `.gitignore` churn would be
- * a confusing, unexplained line in every turn's diff. A no-op for a
- * `scratch` workspace (no `.git` at all, resolved by `resolveGitDir`) and for
- * anything that goes wrong reading or writing it — this is housekeeping, not
- * a security boundary on its own (the per-file and per-attachment safeguards
- * above are), and must never fail a turn.
+ * Add one pattern to a repository workspace's local exclude file. Shared by
+ * attachments and Space files (P9): both are mirrors of stored bytes that an
+ * agent must not commit by accident.
  */
-async function excludeAttachmentsDirFromGit(workspaceDir, logger) {
+async function excludePatternFromGit(workspaceDir, pattern, logger) {
     const gitDir = await resolveGitDir(workspaceDir);
     if (!gitDir)
         return;
     const excludePath = (0, node_path_1.join)(gitDir, 'info', 'exclude');
-    const pattern = `/${exports.ATTACHMENTS_DIR}/`;
     try {
         let existing = '';
         try {
@@ -226,9 +217,26 @@ async function excludeAttachmentsDirFromGit(workspaceDir, logger) {
         await (0, promises_1.appendFile)(excludePath, `${prefix}${pattern}\n`);
     }
     catch (error) {
-        logger.warn(`[attachments] could not add ${exports.ATTACHMENTS_DIR}/ to ${excludePath}: ${error instanceof Error ? error.message : String(error)}`);
+        logger.warn(`[attachments] could not add ${pattern} to ${excludePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * Best-effort: keep `attachments/` out of `git status` in a repository-mode
+ * workspace, so an agent that stages "everything that changed" cannot commit
+ * a user's uploaded file into the repository it is working on.
+ *
+ * Written to `<gitdir>/info/exclude`, NOT `.gitignore` — the former is local
+ * to this checkout and is never itself a tracked file the agent could commit
+ * or a diff it could see, which matters because `.gitignore` churn would be
+ * a confusing, unexplained line in every turn's diff. A no-op for a
+ * `scratch` workspace (no `.git` at all, resolved by `resolveGitDir`) and for
+ * anything that goes wrong reading or writing it — this is housekeeping, not
+ * a security boundary on its own (the per-file and per-attachment safeguards
+ * above are), and must never fail a turn.
+ */
+async function excludeAttachmentsDirFromGit(workspaceDir, logger) {
+    await excludePatternFromGit(workspaceDir, `/${exports.ATTACHMENTS_DIR}/`, logger);
+}
 /**
  * Download every attachment into `<workspaceDir>/attachments/`.
  *

package/dist/runtime/conversation.d.ts

@@ -72,6 +72,22 @@ export declare function trimHistory(history: ModelMessage[], maxChars?: number):
  * Returns the raw input unchanged when there is nothing to replay, so a first
  * turn is byte-for-byte what it always was and cannot regress.
  */
+/**
+ * THE KEY ONE AGENT'S CONVERSATION IS STORED UNDER on this runner.
+ *
+ * A chat can be answered by several agents, and each agent keeps its own
+ * thread: its model memory and its backend checkpoint. Keying by the chat alone
+ * would hand agent B the replay of agent A's answers. The transcript itself
+ * stays keyed by the chat; only this memory is per agent.
+ *
+ * A session with no agent id (an older control plane) keeps the chat-only key.
+ */
+export declare function conversationKey(session: {
+    sessionId: string;
+    agent?: {
+        agentId?: string;
+    } | null;
+}): string;
 export declare function buildReplayPrompt(history: ModelMessage[], input: string): string;
 /**
  * Reduce a turn's projected parts to the assistant text the model produced.

package/dist/runtime/conversation.js

@@ -36,6 +36,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_REPLAY_CHARS = void 0;
 exports.trimHistory = trimHistory;
+exports.conversationKey = conversationKey;
 exports.buildReplayPrompt = buildReplayPrompt;
 exports.assistantTextFrom = assistantTextFrom;
 /**
@@ -121,6 +122,20 @@ function trimHistory(history, maxChars = exports.MAX_REPLAY_CHARS) {
  * Returns the raw input unchanged when there is nothing to replay, so a first
  * turn is byte-for-byte what it always was and cannot regress.
  */
+/**
+ * THE KEY ONE AGENT'S CONVERSATION IS STORED UNDER on this runner.
+ *
+ * A chat can be answered by several agents, and each agent keeps its own
+ * thread: its model memory and its backend checkpoint. Keying by the chat alone
+ * would hand agent B the replay of agent A's answers. The transcript itself
+ * stays keyed by the chat; only this memory is per agent.
+ *
+ * A session with no agent id (an older control plane) keeps the chat-only key.
+ */
+function conversationKey(session) {
+    const agentId = session.agent?.agentId;
+    return agentId ? `${session.sessionId}#${agentId}` : session.sessionId;
+}
 function buildReplayPrompt(history, input) {
     const trimmed = trimHistory(history);
     if (trimmed.length === 0)

package/dist/runtime/dev-server-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The dev-server / scaffolding guard for coding-agent turns.
+ *
+ * A report or dashboard is delivered as an artifact. Without this guard the
+ * agent starts a Node app and a dev server instead, which the user cannot open
+ * from the session UI and which leaks a port into the sandbox.
+ *
+ * ── WHY `devServerCommandKind` IS SELF-CONTAINED ──────────────────────────
+ * The Pi extension that enforces the refusal runs as a separate process, so it
+ * cannot import this module. It embeds the matcher's SOURCE via `toString()`.
+ * That is only safe if the function references nothing outside its own body:
+ * no module-level constants, no imports, no closures. Keep it that way; the
+ * test that evaluates the embedded copy catches any slip.
+ */
+export declare const DEV_SERVER_REFUSAL = "Reports and dashboards are delivered as artifacts. Use create_artifact (see the html-dashboard skill).";
+/**
+ * Returns a short label for the kind of dev-server or scaffolding command, or
+ * null when the command is not one. Positive and negative cases are pinned in
+ * the tests.
+ */
+export declare function devServerCommandKind(command: string): string | null;
+/**
+ * True when the user's message explicitly asks for an app, server, API or
+ * project. Verb and noun must sit close together, so "create a sales dashboard
+ * for our app" does not count and "build me an Express API" does.
+ */
+export declare function userAsksForApp(text: string): boolean;
+/**
+ * Whether THIS turn's shell calls are subject to the dev-server refusal.
+ * The per-turn decision the Pi backend writes to the policy file.
+ */
+export declare function turnBlocksDevServers(policy: {
+    blockDevServers?: boolean;
+} | null | undefined, userMessage: string): boolean;
+/**
+ * The refusal, or null when the command may run. `blockDevServers` is the
+ * per-agent policy; an explicit app request in the turn overrides it.
+ */
+export declare function devServerRefusalFor(input: {
+    command: string;
+    blockDevServers: boolean;
+    userMessage: string;
+}): string | null;

package/dist/runtime/dev-server-guard.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * The dev-server / scaffolding guard for coding-agent turns.
+ *
+ * A report or dashboard is delivered as an artifact. Without this guard the
+ * agent starts a Node app and a dev server instead, which the user cannot open
+ * from the session UI and which leaks a port into the sandbox.
+ *
+ * ── WHY `devServerCommandKind` IS SELF-CONTAINED ──────────────────────────
+ * The Pi extension that enforces the refusal runs as a separate process, so it
+ * cannot import this module. It embeds the matcher's SOURCE via `toString()`.
+ * That is only safe if the function references nothing outside its own body:
+ * no module-level constants, no imports, no closures. Keep it that way; the
+ * test that evaluates the embedded copy catches any slip.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEV_SERVER_REFUSAL = void 0;
+exports.devServerCommandKind = devServerCommandKind;
+exports.userAsksForApp = userAsksForApp;
+exports.turnBlocksDevServers = turnBlocksDevServers;
+exports.devServerRefusalFor = devServerRefusalFor;
+exports.DEV_SERVER_REFUSAL = 'Reports and dashboards are delivered as artifacts. Use create_artifact (see the html-dashboard skill).';
+/**
+ * Returns a short label for the kind of dev-server or scaffolding command, or
+ * null when the command is not one. Positive and negative cases are pinned in
+ * the tests.
+ */
+function devServerCommandKind(command) {
+    const text = String(command || '');
+    const checks = [
+        ['scaffold', /\b(npm|pnpm|yarn|bun)\s+(create|init)\b/],
+        ['scaffold', /\bnpx\s+create-[\w-]+/],
+        [
+            'dev-server',
+            /(^|[;&|(]\s*)(npx\s+|pnpm\s+(exec\s+)?|yarn\s+)?(vite|next)(\s+(dev|start|serve))?(\s|$|[;&|)])/m
+        ],
+        ['dev-server', /\b(vite|next)\s+(dev|serve)\b/],
+        ['dev-server', /\bnode\s+(-e\s+)?['"]?[^\n]*\.listen\s*\(/],
+        ['dev-server', /\bnode\s+\S*(server|app|api)\S*\.(c|m)?js\b/],
+        ['dev-server', /(^|\s)--port(\s|=)/],
+        ['dev-server', /\b(uvicorn|flask\s+run|python3?\s+-m\s+http\.server)\b/]
+    ];
+    for (const [kind, pattern] of checks) {
+        if (pattern.test(text))
+            return kind;
+    }
+    return null;
+}
+/**
+ * True when the user's message explicitly asks for an app, server, API or
+ * project. Verb and noun must sit close together, so "create a sales dashboard
+ * for our app" does not count and "build me an Express API" does.
+ */
+function userAsksForApp(text) {
+    return /\b(build|create|make|write|scaffold|set\s+up|start|run|deploy)\s+(me\s+|us\s+|a\s+|an\s+|the\s+|my\s+|our\s+|new\s+)*((?!(dashboard|report|chart|graph|summary|table|diagram|spreadsheet)\b)\w+\s+){0,3}(app|application|api|server|service|website|project|repo|repository|express|backend)\b/i.test(String(text || ''));
+}
+/**
+ * Whether THIS turn's shell calls are subject to the dev-server refusal.
+ * The per-turn decision the Pi backend writes to the policy file.
+ */
+function turnBlocksDevServers(policy, userMessage) {
+    return policy?.blockDevServers === true && !userAsksForApp(userMessage);
+}
+/**
+ * The refusal, or null when the command may run. `blockDevServers` is the
+ * per-agent policy; an explicit app request in the turn overrides it.
+ */
+function devServerRefusalFor(input) {
+    if (!input.blockDevServers)
+        return null;
+    if (userAsksForApp(input.userMessage))
+        return null;
+    return devServerCommandKind(input.command) ? exports.DEV_SERVER_REFUSAL : null;
+}

package/dist/runtime/knowledge-tools.d.ts

@@ -0,0 +1,44 @@
+import type { KnowledgeDownloadResponse, KnowledgeFilesResponse } from '../types';
+/** The name the agent sees the server under. */
+export declare const KNOWLEDGE_SERVER_NAME = "pf-knowledge";
+export declare const KNOWLEDGE_FILES_LIST_TOOL = "knowledge_files_list";
+export declare const KNOWLEDGE_FILE_DOWNLOAD_TOOL = "knowledge_file_download";
+/** The control plane's answers, as this module needs them. Injected for tests. */
+export interface KnowledgeControl {
+    list(datastoreId?: string): Promise<KnowledgeFilesResponse>;
+    download(datastoreId: string, fileId: string): Promise<KnowledgeDownloadResponse>;
+}
+/** The active turn a session's tools act for. Absent between turns. */
+export interface KnowledgeTurn {
+    control: KnowledgeControl;
+    workspaceDir: string;
+}
+/** A name safe as one path segment, for a download's name. */
+export declare function safeDownloadName(raw: unknown): string;
+export interface KnowledgeToolHostOptions {
+    fetchImpl?: typeof fetch;
+    logger: Pick<Console, 'log' | 'warn' | 'error'>;
+    downloadTimeoutMs?: number;
+}
+export declare class KnowledgeToolHost {
+    private readonly options;
+    private server;
+    private port;
+    private starting;
+    private readonly tokenBySession;
+    private readonly sessionByToken;
+    private readonly turns;
+    constructor(options: KnowledgeToolHostOptions);
+    /** The endpoint a session's agent is configured with. Starts the listener on first use. */
+    endpointFor(sessionId: string): Promise<string>;
+    /** Bind the current turn's lease, or clear it with null when the turn ends. */
+    bindTurn(sessionId: string, turn: KnowledgeTurn | null): void;
+    stop(): Promise<void>;
+    private start;
+    private handle;
+    private send;
+    private dispatch;
+    private callTool;
+    private list;
+    private download;
+}