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

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/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;
+}