@hachej/boring-agent 0.2.1 → 0.2.2

package/README.md

@@ -118,6 +118,20 @@ Deviations, honestly:
 - Cost: the compactor makes about two calls per message, each carrying the view as context. Choose a cheap summarizer model; the browser-agent example uses the chat model only because it has one.
 - The package runs in Node and in a browser (no Node-only imports). Fictional-data tests are in `test/packages/agent.test.mjs`; `examples/bot` and `examples/browser-agent` have journeys.
 
+## Per-request prompt context
+
+`@hachej/boring-agent/prompt-context` (`createPromptContext({ context })`) is one ordinary native extension whose `GenerationHooks.beforeRequest` (registered with `hook(GenerationTask, ...)`) runs before every request attempt, retries and crash recovery included. The hook's text is used for that request only: it is recomputed each time and never appended to the transcript. The text is one user-role `<request-context>...</request-context>` message placed immediately before the round's question when the final message is the user's question, otherwise at the tail (after tool results or an assistant continuation); system messages and earlier messages are unchanged, so the stable prefix stays cacheable.
+
+Choose the seam by how the text changes and who should see it:
+
+- Stable per-agent text (instructions, a fixed section): `AgentSpec.instructions` or a `PromptSection`. Pi stores a system entry whenever a section's text changes, so use it only for text that changes rarely.
+- Volatile or private text (the open document, the time, a permission snapshot): this hook. Nothing is stored and the person does not see it in the history.
+- Text the person should see and keep: `prepareInput` on the submit route, which becomes the user message.
+
+`context({ conversationId, messages, signal })` returns the text (`undefined` or `''` adds nothing). The host keeps request-scoped state in its own store keyed by `conversationId` and reads it there; Pi's hook context carries no caller values. Install several extensions to compose independent contexts (they apply in install order).
+
+Failure is fail-open and Pi's: a throwing `context` is reported through `HarnessOptions.onReport` and the request goes out without the context (Pi's `hooks.each`, scheduler.js). An aborted turn rethrows. This is advisory text, not policy or authorization; do not use it to enforce a decision. The text is sent to the model provider and gateways or telemetry that log request bodies may see it; the model can quote it into a stored assistant message. Compaction summarizes the stored transcript only, so the context is not folded into summaries. After a crash the hook runs again at recovery, so the value is fresh per attempt, not replayed. Placement: before the round's question when that is the last message; after tool results or an assistant continuation, at the tail. Tests: `test/packages/agent-prompt-context.test.mjs`.
+
 ## Native questions
 
 `createQuestions` from `@hachej/boring-agent/questions` exposes a native task, session document family and extension. Install the extension explicitly. Call `admit(tx, question, ownership, context)` in a native commit to persist a single-choice question and its task together. `resolve` and `consume` take the caller's native transaction so host writes can share that atomic commit. Call them before host table writes: native task reads after a table write are unavailable and the operation returns conflict. Host authentication and current subject/policy checks run at both boundaries. A resolved answer is clarification, never publication permission.

package/dist/artifacts.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@earendil-works/pi-durable';
 import { Type } from '@earendil-works/pi-ai';
+import { workspacePath } from '@hachej/boring-files/file-types';
 import { asWorkspaceResolver, workspaceFor } from './workspaces.js';
 /*
  * Artifacts: substantial, self-contained content (a document, an HTML page, an SVG, code) that a chat shows as a card
@@ -70,12 +71,13 @@ const decode = (bytes) => { try {
 catch {
     return undefined;
 } };
-const PRESENTED = {
+// Null-prototype tables: a name such as `constructor` is not an entry.
+const PRESENTED = Object.assign(Object.create(null), {
     md: { type: 'markdown', mediaType: 'text/markdown' }, markdown: { type: 'markdown', mediaType: 'text/markdown' },
     html: { type: 'html', mediaType: 'text/html' }, htm: { type: 'html', mediaType: 'text/html' },
     svg: { type: 'svg', mediaType: 'image/svg+xml' }, tldraw: { type: 'canvas', mediaType: 'application/vnd.tldraw+json' },
-};
-const LANGUAGE_OF = { js: 'javascript', mjs: 'javascript', ts: 'typescript', py: 'python', json: 'json', css: 'css', sql: 'sql', yaml: 'yaml', yml: 'yaml', sh: 'shell', rs: 'rust', go: 'go', java: 'java', csv: 'csv' };
+});
+const LANGUAGE_OF = Object.assign(Object.create(null), { js: 'javascript', mjs: 'javascript', ts: 'typescript', py: 'python', json: 'json', css: 'css', sql: 'sql', yaml: 'yaml', yml: 'yaml', sh: 'shell', rs: 'rust', go: 'go', java: 'java', csv: 'csv' });
 /**
  * `present(path)`: show a workspace file to the person as a card and a side panel. The agent writes the file with its ordinary file
  * tools first. The card points at the file; the file's history (the provider's) is its list of versions. Nothing is written here.
@@ -95,7 +97,10 @@ export function createPresentTool(options = {}) {
         parameters: Type.Object({ path: Type.String({ minLength: 1, maxLength: 512, description: 'The file path, relative to the workspace.' }) }, { additionalProperties: false }),
         replay: 'safe',
         execute: async (args, api, context) => {
-            const path = args.path.replace(/^\.\//, '');
+            // An absolute path is refused, not normalised: `/workspace/a.md` must never be read as `workspace/a.md` under the root.
+            if (args.path.startsWith('/'))
+                return reply({ kind: 'denied', reason: 'The path must be relative to the workspace' });
+            const path = workspacePath(args.path);
             const resolved = await workspaceFor(resolver, api, context);
             if ('refused' in resolved)
                 return reply({ kind: 'denied', reason: resolved.refused });

package/dist/file-types.d.ts

@@ -1,14 +1,10 @@
 export type FileKind = 'text' | 'pdf' | 'office' | 'image' | 'archive' | 'binary';
-/** The lower-case extension of the last path segment, or ''. */
-export declare const extensionOf: (path: string) => string;
 /** The media type of a native image (png, jpeg, gif, webp) by extension, or undefined. */
 export declare const nativeImageType: (path: string) => string | undefined;
 /** How many leading bytes `fileKind` looks at. */
 export declare const SNIFF_BYTES = 16;
 /** The kind of `path`, from its extension and, when given, its leading bytes (the magic number wins). Unknown extensions are text unless a NUL byte says otherwise. */
 export declare function fileKind(path: string, head?: Uint8Array): FileKind;
-/** The media type a file's leading bytes name (a PDF or an image signature), or undefined. */
-export declare function sniffedMediaType(head: Uint8Array): string | undefined;
 /**
  * The media type a converter should be told. A signature in the leading bytes wins over everything (a PDF named `.txt` is
  * `application/pdf`, whatever the provider derived from the name); then the provider's type unless it is generic; then the table's.

package/dist/file-types.js

@@ -1,6 +1,7 @@
 /*
- * The one table of file types the agent package routes by. `read` (file-convert.ts) decides whether Pi's native read or the host's
- * converter handles a file; the mention resolver (mentions.ts) decides what to put in a message. Both ask `fileKind`.
+ * The file kinds the agent package routes by. `read` (file-convert.ts) decides whether Pi's native read or the host's converter
+ * handles a file; the mention resolver (mentions.ts) decides what to put in a message. Both ask `fileKind`.
+ * Media types, extensions and magic numbers come from `@hachej/boring-files/file-types`; this file only says which kind each is.
  *
  *  - `text`: Pi's native read, untouched.
  *  - `pdf`, `office`, `image`: a host converter can turn them into text; Pi's read cannot (it returns garbage for a PDF).
@@ -10,33 +11,28 @@
  * A file is classified by its extension AND its leading bytes: a PDF or an image is recognised by its magic number even under a
  * wrong name.
  */
+import { MEDIA_TYPES, extensionOf, sniffMediaType } from '@hachej/boring-files/file-types';
 const TEXT = ['md', 'markdown', 'txt', 'csv', 'tsv', 'json', 'jsonl', 'html', 'htm', 'svg', 'xml', 'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'css', 'py', 'sql', 'yaml', 'yml', 'sh', 'toml', 'ini', 'log', 'rst', 'tex'];
 const OFFICE = ['doc', 'docx', 'odt', 'rtf', 'xls', 'xlsx', 'ods', 'ppt', 'pptx', 'odp', 'epub'];
-/** Image extensions and their media types; `native` ones a model reads as an image part without conversion. */
-const IMAGES = {
-    png: { mediaType: 'image/png', native: true }, jpg: { mediaType: 'image/jpeg', native: true }, jpeg: { mediaType: 'image/jpeg', native: true },
-    gif: { mediaType: 'image/gif', native: true }, webp: { mediaType: 'image/webp', native: true },
-    bmp: { mediaType: 'image/bmp', native: false }, tif: { mediaType: 'image/tiff', native: false }, tiff: { mediaType: 'image/tiff', native: false },
-};
+/** Image extensions; `native` ones a model reads as an image part without conversion. Their media types are `MEDIA_TYPES`. */
+const IMAGES = Object.assign(Object.create(null), { png: true, jpg: true, jpeg: true, gif: true, webp: true, bmp: false, tif: false, tiff: false });
 const BY_EXTENSION = new Map([
     ...TEXT.map(extension => [extension, 'text']),
     ...OFFICE.map(extension => [extension, 'office']),
     ...Object.keys(IMAGES).map(extension => [extension, 'image']),
     ['pdf', 'pdf'], ['zip', 'archive'],
 ]);
-/** The lower-case extension of the last path segment, or ''. */
-export const extensionOf = (path) => { const dot = path.lastIndexOf('.'); return dot > path.lastIndexOf('/') ? path.slice(dot + 1).toLowerCase() : ''; };
 /** The media type of a native image (png, jpeg, gif, webp) by extension, or undefined. */
-export const nativeImageType = (path) => { const image = IMAGES[extensionOf(path)]; return image?.native ? image.mediaType : undefined; };
+export const nativeImageType = (path) => IMAGES[extensionOf(path)] === true ? MEDIA_TYPES[extensionOf(path)] : undefined;
 /** How many leading bytes `fileKind` looks at. */
 export const SNIFF_BYTES = 16;
 const startsWith = (bytes, signature, at = 0) => signature.every((byte, index) => bytes[at + index] === byte);
 /** The kind a magic number names, or undefined. A ZIP signature is an office document only under an office extension. */
 function kindByMagic(bytes, extension) {
-    if (startsWith(bytes, [0x25, 0x50, 0x44, 0x46, 0x2d]))
+    const sniffed = sniffMediaType(bytes);
+    if (sniffed === 'application/pdf')
         return 'pdf';
-    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47]) || startsWith(bytes, [0xff, 0xd8, 0xff]) || startsWith(bytes, [0x47, 0x49, 0x46, 0x38])
-        || (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) && startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8)) || startsWith(bytes, [0x42, 0x4d]) && extension === 'bmp')
+    if (sniffed?.startsWith('image/') || (startsWith(bytes, [0x42, 0x4d]) && extension === 'bmp'))
         return 'image';
     if (startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]))
         return OFFICE.includes(extension) ? 'office' : 'archive';
@@ -57,37 +53,16 @@ export function fileKind(path, head) {
     }
     return named ?? 'text';
 }
-const OFFICE_TYPES = {
-    doc: 'application/msword', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-    odt: 'application/vnd.oasis.opendocument.text', ods: 'application/vnd.oasis.opendocument.spreadsheet', odp: 'application/vnd.oasis.opendocument.presentation',
-    rtf: 'application/rtf', epub: 'application/epub+zip',
-};
-/** The media type a file's leading bytes name (a PDF or an image signature), or undefined. */
-export function sniffedMediaType(head) {
-    if (startsWith(head, [0x25, 0x50, 0x44, 0x46, 0x2d]))
-        return 'application/pdf';
-    if (startsWith(head, [0x89, 0x50, 0x4e, 0x47]))
-        return 'image/png';
-    if (startsWith(head, [0xff, 0xd8, 0xff]))
-        return 'image/jpeg';
-    if (startsWith(head, [0x47, 0x49, 0x46, 0x38]))
-        return 'image/gif';
-    if (startsWith(head, [0x52, 0x49, 0x46, 0x46]) && startsWith(head, [0x57, 0x45, 0x42, 0x50], 8))
-        return 'image/webp';
-    return undefined;
-}
 /**
  * The media type a converter should be told. A signature in the leading bytes wins over everything (a PDF named `.txt` is
  * `application/pdf`, whatever the provider derived from the name); then the provider's type unless it is generic; then the table's.
  */
 export function mediaTypeFor(path, kind, provided, head) {
-    const sniffed = head === undefined ? undefined : sniffedMediaType(head);
+    const sniffed = head === undefined ? undefined : sniffMediaType(head);
     if (sniffed !== undefined)
         return sniffed;
     const extension = extensionOf(path);
-    const table = kind === 'pdf' ? 'application/pdf' : kind === 'image' ? IMAGES[extension]?.mediaType : kind === 'office' ? OFFICE_TYPES[extension] : undefined;
+    const table = kind === 'pdf' ? MEDIA_TYPES.pdf : kind === 'image' && IMAGES[extension] !== undefined ? MEDIA_TYPES[extension] : kind === 'office' && OFFICE.includes(extension) ? MEDIA_TYPES[extension] : undefined;
     const generic = !provided || provided === 'application/octet-stream' || provided.startsWith('text/') || provided === 'application/zip';
     if (!generic)
         return provided;

package/dist/mentions.js

@@ -1,4 +1,5 @@
-import { SNIFF_BYTES, extensionOf, fileKind, nativeImageType } from './file-types.js';
+import { extensionOf } from '@hachej/boring-files/file-types';
+import { SNIFF_BYTES, fileKind, nativeImageType } from './file-types.js';
 export const MENTION_LIMITS = Object.freeze({ fileBytes: 100_000, totalBytes: 300_000, files: 20 });
 /** Every part this module adds starts with this prefix, so a viewer can tell it from what the person typed. */
 export const MENTION_FILE_PREFIX = '<file path="';

package/dist/prompt-context.d.ts

@@ -0,0 +1,25 @@
+import type { ConversationId, Extension } from '@earendil-works/pi-durable';
+import type { Message } from '@earendil-works/pi-ai';
+export interface PromptContextInput {
+    readonly conversationId: ConversationId;
+    /** The request's messages as Pi would send them (read-only). */
+    readonly messages: readonly Message[];
+    /** The task's abort signal, when there is one. */
+    readonly signal: AbortSignal | undefined;
+}
+export interface PromptContextOptions {
+    /** Extension name (default `host.prompt-context`). Install one extension per independent context; they compose in install order. */
+    readonly name?: string;
+    /** Wrapper tag of the message (default `request-context`). */
+    readonly tag?: string;
+    /** Fresh text for this request attempt; `undefined` or `''` adds no message. */
+    readonly context: (input: PromptContextInput) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * The request messages with one user message carrying `text` added. It goes right before the round's question (the last message
+ * that is not a context from an earlier extension) when that is a user message; otherwise (after tool results, or after an
+ * assistant continuation) at the tail. Pure: the input array is not changed.
+ */
+export declare function withRequestContext(messages: readonly Message[], text: string, tag?: string): Message[];
+export declare function createPromptContext(options: PromptContextOptions): Extension;
+//# sourceMappingURL=prompt-context.d.ts.map

package/dist/prompt-context.js

@@ -0,0 +1,38 @@
+// Per-request prompt context as one ordinary native pi-durable extension. Extension point: `GenerationHooks.beforeRequest`,
+// registered with `hook(GenerationTask, ...)`. Pi runs it before every request attempt (retries and crash recovery included)
+// and uses its result for that request only, so the text is recomputed each time and never appended to the transcript.
+// The host owns the data: `context` reads its own request-scoped state keyed by the conversation (Pi's hook context carries no
+// caller values). Failure is Pi's: Pi's `hooks.each` reports a throw through `HarnessOptions.onReport`, continues the request
+// without this hook's result, and rethrows only when the turn is aborted (scheduler.js, `hooks.each`). Advisory only: never use
+// it for policy or authorization.
+import { GenerationTask, defineExtension, hook } from '@earendil-works/pi-durable';
+/** Messages made by this module, so a later extension skips them when it looks for the round's question (install order holds). */
+const produced = new WeakSet();
+/**
+ * The request messages with one user message carrying `text` added. It goes right before the round's question (the last message
+ * that is not a context from an earlier extension) when that is a user message; otherwise (after tool results, or after an
+ * assistant continuation) at the tail. Pure: the input array is not changed.
+ */
+export function withRequestContext(messages, text, tag = 'request-context') {
+    const message = { role: 'user', content: [{ type: 'text', text: `<${tag}>\n${text}\n</${tag}>` }], timestamp: Date.now() };
+    produced.add(message);
+    let end = messages.length;
+    while (end > 0 && produced.has(messages[end - 1]))
+        end--;
+    const question = messages[end - 1];
+    const at = question?.role === 'user' ? end - 1 : messages.length;
+    return [...messages.slice(0, at), message, ...messages.slice(at)];
+}
+export function createPromptContext(options) {
+    return defineExtension({
+        name: options.name ?? 'host.prompt-context',
+        hooks: [hook(GenerationTask, {
+                beforeRequest: async (request, api, context) => {
+                    const text = await options.context({ conversationId: api.conversationId, messages: request.messages, signal: context.abortSignal });
+                    if (!text)
+                        return undefined;
+                    return { messages: withRequestContext(request.messages, text, options.tag) };
+                },
+            })],
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -125,14 +125,18 @@
     "./metering": {
       "types": "./dist/metering.d.ts",
       "import": "./dist/metering.js"
+    },
+    "./prompt-context": {
+      "types": "./dist/prompt-context.d.ts",
+      "import": "./dist/prompt-context.js"
     }
   },
   "peerDependencies": {
-    "@earendil-works/pi-durable": "1.1.0",
-    "@earendil-works/pi-ai": "1.1.0",
-    "@earendil-works/chord": "1.1.0",
-    "@hachej/boring-files": "0.2.1",
-    "@hachej/boring-ui-kit": "0.2.1"
+    "@earendil-works/pi-durable": "^1.1.0",
+    "@earendil-works/pi-ai": "^1.1.0",
+    "@earendil-works/chord": "^1.1.0",
+    "@hachej/boring-files": "^0.2.2",
+    "@hachej/boring-ui-kit": "^0.2.2"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {