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

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/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/session-runner.js

@@ -2084,6 +2084,7 @@ class SessionRunner {
             // more than the tidier name.
             taskId: session.sessionId,
             workspaceDir,
+            devServerPolicy: session.agent.devServerPolicy,
             model: qualifiedModelId(session.agent.model),
             systemPrompt: session.agent.systemPrompt ?? undefined,
             skills: session.agent.skills.map((skill) => ({

package/dist/types.d.ts

@@ -467,6 +467,13 @@ export interface LeasedAgent {
     /** Always the skill's PUBLISHED content, never its draft. */
     skills: LeasedSkill[];
     mcpServers: LeasedMcpServer[];
+    /**
+     * Optional and additive. Absent means an older control plane, and the
+     * harness then applies no dev-server refusal.
+     */
+    devServerPolicy?: {
+        blockDevServers: boolean;
+    };
 }
 export interface LeasedModel {
     provider: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.3",
+  "version": "0.2.4-rc.1",
   "description": "Headless Peakflo coding-agent harness. One codebase, three hosting modes: a Daytona cloud sandbox, a customer VM, and the 20x desktop.",
   "license": "MIT",
   "type": "commonjs",