@peakflo/agent-harness 0.2.11 → 0.2.12-rc.1

package/dist/adapters/acp-adapter.js

@@ -24,6 +24,9 @@ exports.AcpAdapter = exports.ACP_SESSION_START_TIMEOUT_MS = void 0;
  *   - an asking permission mode puts Cursor in a read-only mode, or the turn
  *     is refused; "always allow" is not offered to the person answering and
  *     is not what a bypass turn answers with
+ *   - the agent's system prompt is sent once, as a delimited block ahead of
+ *     the first prompt of a NEW session (`./session-instructions.ts`); a
+ *     loaded session already has it, and its echo is kept out of the transcript
  */
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
@@ -33,6 +36,7 @@ const util_1 = require("util");
 const coding_agent_adapter_1 = require("./coding-agent-adapter");
 const vendor_environment_1 = require("./vendor-environment");
 const cursor_acp_1 = require("./cursor-acp");
+const session_instructions_1 = require("./session-instructions");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 /**
  * The ACP options known to answer ONE request (`allow_once`, `reject_once`).
@@ -331,7 +335,10 @@ class AcpAdapter {
             toolCallMetadata: new Map(),
             lastError: null,
             codexUseApiKey,
-            codexAuthSummary
+            codexAuthSummary,
+            // ACP has no system-prompt field; the first prompt carries it once.
+            pendingInstructions: (0, session_instructions_1.sessionInstructionsBlock)(config.systemPrompt),
+            instructionsInFlight: null
         };
         // Temporarily store with workspace ID, will re-key after getting ACP session ID
         this.sessions.set(sessionId, session);
@@ -487,7 +494,12 @@ class AcpAdapter {
             toolCallMetadata: new Map(),
             lastError: null,
             codexUseApiKey,
-            codexAuthSummary
+            codexAuthSummary,
+            // A loaded session was given the instructions on its first turn and the
+            // agent keeps them in its own history; sending them again would repeat
+            // them in the conversation on every turn.
+            pendingInstructions: null,
+            instructionsInFlight: null
         };
         // Store with the Codex UUID (same as sessionId since we now return UUID from createSession)
         this.sessions.set(sessionId, session);
@@ -595,12 +607,22 @@ class AcpAdapter {
         session.currentTurnId++;
         session.activeTurnId = session.currentTurnId;
         session.lastChunkTime = null;
+        // The system prompt goes once, as its own block ahead of the first
+        // message of a new session. It is not part of the user's prompt above,
+        // so the transcript and the runner's echo filter see only the user's text.
+        const instructions = session.pendingInstructions;
+        session.pendingInstructions = null;
+        // Recorded before the write: the answer can arrive as soon as it is sent.
+        session.instructionsInFlight = instructions
+            ? { requestId: session.nextRequestId, block: instructions }
+            : null;
         // Send prompt via ACP (prompt must be an array of ContentBlock objects)
         // Note: session/prompt is a long-running operation that responds via session/update notifications
         // We send the request but don't await the response to avoid timeout
         this.sendRpcRequestNoWait(session, 'session/prompt', {
             sessionId: session.acpSessionId,
             prompt: [
+                ...(instructions ? [{ type: 'text', text: instructions }] : []),
                 {
                     type: 'text',
                     text: promptText
@@ -899,6 +921,16 @@ class AcpAdapter {
             }
             // No pending request - could be error for permission response or other async operation
             const response = message;
+            // The prompt that carried the system-prompt block has been answered. A
+            // refused prompt never reached the agent's history, so the block goes
+            // again with the next prompt instead of being lost for the session.
+            const inFlight = session.instructionsInFlight;
+            if (inFlight && inFlight.requestId === message.id) {
+                session.instructionsInFlight = null;
+                if ('error' in response && response.error) {
+                    session.pendingInstructions = inFlight.block;
+                }
+            }
             if ('error' in response && response.error) {
                 // Check for quota/usage limit errors from the provider
                 const errorInfo = this.extractCodexErrorInfo(response.error);
@@ -1751,27 +1783,33 @@ class AcpAdapter {
                     const currentText = partContentLengths.get(userId) || '';
                     const newText = this.mergeStreamingText(currentText, chunk);
                     partContentLengths.set(userId, newText);
-                    // Return update part with accumulated text
-                    parts.push({
-                        id: userId,
-                        type: coding_agent_adapter_1.MessagePartType.TEXT,
-                        text: newText,
-                        role: 'user',
-                        update: seenPartIds.has(userId)
-                    });
-                    seenPartIds.add(userId);
+                    // The echo of the system-prompt block is not the user's words.
+                    const visibleText = (0, session_instructions_1.stripSessionInstructions)(newText);
+                    if (visibleText) {
+                        // Return update part with accumulated text
+                        parts.push({
+                            id: userId,
+                            type: coding_agent_adapter_1.MessagePartType.TEXT,
+                            text: visibleText,
+                            role: 'user',
+                            update: seenPartIds.has(userId)
+                        });
+                        seenPartIds.add(userId);
+                    }
                 }
             }
             else if (update.sessionUpdate === 'agent_message' ||
                 update.sessionUpdate === 'assistant_message' ||
                 update.sessionUpdate === 'user_message' ||
                 update.sessionUpdate === 'human_message') {
-                const text = this.extractTextFromUpdateContent(update.content);
-                if (!text)
-                    return parts;
                 const role = update.sessionUpdate === 'user_message' || update.sessionUpdate === 'human_message'
                     ? 'user'
                     : 'assistant';
+                const rawText = this.extractTextFromUpdateContent(update.content);
+                // The echo of the system-prompt block is not the user's words.
+                const text = role === 'user' ? (0, session_instructions_1.stripSessionInstructions)(rawText) : rawText;
+                if (!text)
+                    return parts;
                 // For assistant messages without a stable messageId, derive a
                 // deterministic ID from the current turn so it matches the streaming
                 // chunk ID (`agent-response-{turnId}`).  This prevents duplicates

package/dist/adapters/opencode-adapter.js

@@ -1462,6 +1462,15 @@ class OpencodeAdapter {
     async executePromptWithRetry(ocClient, sessionId, parts, modelParam, config, promptAbort) {
         const maxRetries = OpencodeAdapter.PROMPT_MAX_RETRIES;
         const baseDelay = OpencodeAdapter.PROMPT_RETRY_BASE_DELAY_MS;
+        /*
+         * The agent's system prompt goes in OpenCode's own `system` field, which
+         * the server adds to the model's system prompt for this request. It is
+         * kept on the user message, not added to the conversation, so it is sent
+         * with every prompt: a turn without it would run without the agent's
+         * instructions. Trimmed only, so the bytes stay the same turn to turn and
+         * the prompt prefix stays cacheable. An empty prompt sends no field.
+         */
+        const system = config.systemPrompt?.trim() || undefined;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             if (promptAbort.signal.aborted)
                 return;
@@ -1475,6 +1484,7 @@ class OpencodeAdapter {
                     body: {
                         parts: parts,
                         ...(modelParam && { model: modelParam }),
+                        ...(system && { system }),
                         ...(config.tools && { tools: config.tools })
                     },
                     ...(config.workspaceDir && {

package/dist/adapters/session-instructions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The control plane's system prompt for a backend that has no system-prompt
+ * slot of its own.
+ *
+ * Pi, Codex and Claude Code take the agent's system prompt natively
+ * (`--append-system-prompt`, `developerInstructions`, the SDK's
+ * `systemPrompt`). ACP has no such field: `session/new` accepts only `cwd` and
+ * `mcpServers`, and Cursor's `cursor-agent acp` documents no `_meta` key for
+ * it. So an ACP session receives the prompt ONCE, as a delimited content block
+ * ahead of the first user message of a new session. The agent keeps its own
+ * conversation, so every later turn (a resumed `session/load`) already has it.
+ *
+ * The wrapper is constant and the prompt is only trimmed, so the bytes the
+ * model sees are the same for the same agent: the conversation prefix stays
+ * cacheable.
+ */
+export declare const SESSION_INSTRUCTIONS_OPEN = "<system_instructions>";
+export declare const SESSION_INSTRUCTIONS_CLOSE = "</system_instructions>";
+/** The block to send ahead of the first prompt, or null when there is none. */
+export declare function sessionInstructionsBlock(systemPrompt: string | null | undefined): string | null;
+/**
+ * The user's text without a leading instructions block.
+ *
+ * An ACP agent may echo the prompt back as `user_message_chunk` updates, live
+ * or when a session is loaded again. The block is not the user's words and
+ * must not reach the transcript. Matched on the delimiters, not on the prompt
+ * text, so a block sent under an older version of the agent's prompt is
+ * removed too. While a streamed echo has not yet reached the closing tag the
+ * whole text is still block, and nothing is shown.
+ */
+export declare function stripSessionInstructions(text: string): string;

package/dist/adapters/session-instructions.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * The control plane's system prompt for a backend that has no system-prompt
+ * slot of its own.
+ *
+ * Pi, Codex and Claude Code take the agent's system prompt natively
+ * (`--append-system-prompt`, `developerInstructions`, the SDK's
+ * `systemPrompt`). ACP has no such field: `session/new` accepts only `cwd` and
+ * `mcpServers`, and Cursor's `cursor-agent acp` documents no `_meta` key for
+ * it. So an ACP session receives the prompt ONCE, as a delimited content block
+ * ahead of the first user message of a new session. The agent keeps its own
+ * conversation, so every later turn (a resumed `session/load`) already has it.
+ *
+ * The wrapper is constant and the prompt is only trimmed, so the bytes the
+ * model sees are the same for the same agent: the conversation prefix stays
+ * cacheable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_INSTRUCTIONS_CLOSE = exports.SESSION_INSTRUCTIONS_OPEN = void 0;
+exports.sessionInstructionsBlock = sessionInstructionsBlock;
+exports.stripSessionInstructions = stripSessionInstructions;
+exports.SESSION_INSTRUCTIONS_OPEN = '<system_instructions>';
+exports.SESSION_INSTRUCTIONS_CLOSE = '</system_instructions>';
+/** The block to send ahead of the first prompt, or null when there is none. */
+function sessionInstructionsBlock(systemPrompt) {
+    const trimmed = systemPrompt?.trim();
+    if (!trimmed)
+        return null;
+    // A closing tag inside the prompt would end the block early, for the model
+    // and for `stripSessionInstructions`, so it is neutralised. Deterministic,
+    // so the bytes stay the same turn to turn.
+    const prompt = trimmed
+        .split(exports.SESSION_INSTRUCTIONS_CLOSE)
+        .join('</ system_instructions>');
+    return [
+        exports.SESSION_INSTRUCTIONS_OPEN,
+        'These are your standing instructions from the platform for this whole session. Follow them in every turn; they are not a message from the user.',
+        '',
+        prompt,
+        exports.SESSION_INSTRUCTIONS_CLOSE
+    ].join('\n');
+}
+/**
+ * The user's text without a leading instructions block.
+ *
+ * An ACP agent may echo the prompt back as `user_message_chunk` updates, live
+ * or when a session is loaded again. The block is not the user's words and
+ * must not reach the transcript. Matched on the delimiters, not on the prompt
+ * text, so a block sent under an older version of the agent's prompt is
+ * removed too. While a streamed echo has not yet reached the closing tag the
+ * whole text is still block, and nothing is shown.
+ */
+function stripSessionInstructions(text) {
+    const start = text.trimStart();
+    if (!start)
+        return text;
+    if (!start.startsWith(exports.SESSION_INSTRUCTIONS_OPEN)) {
+        // A streamed echo can stop part-way through the opening tag. A user
+        // message that is itself a prefix of the tag (`<sys`) is hidden too; at
+        // two characters or more of this exact tag that is accepted.
+        return exports.SESSION_INSTRUCTIONS_OPEN.startsWith(start) && start.length > 1
+            ? ''
+            : text;
+    }
+    const end = start.indexOf(exports.SESSION_INSTRUCTIONS_CLOSE);
+    if (end < 0)
+        return '';
+    return start.slice(end + exports.SESSION_INSTRUCTIONS_CLOSE.length).trimStart();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peakflo/agent-harness",
-  "version": "0.2.11",
+  "version": "0.2.12-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",