@hachej/boring-agent 0.2.3 → 0.2.4

package/README.md

@@ -134,6 +134,8 @@ Choose the seam by how the text changes and who should see it:
 
 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`.
 
+Screen context: a browser can send what the person is looking at with each submit. `createRemoteChat({ requestContext })` adds the returned plain object to the submit body as `context`. In `ChatTransportAccess`, `requestContext(value)` receives it after validation and before `conversation.submit`; a value that is not a plain JSON object of at most 4 KB is `400 invalid-request`, and a host without `requestContext` ignores the field. The host stores `context` by conversation id in `requestContext` and renders it in `createPromptContext({ context })`; the transport keeps nothing. Tests: `test/packages/agent-chat-transport-context.test.mjs`, `test/packages/ui-remote-chat-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/chat-transport.d.ts

@@ -5,6 +5,7 @@ export declare const CHAT_TRANSPORT: Readonly<{
     schema: "boring.chat-transport";
     version: 1;
     maxRequestBytes: 8388608;
+    maxContextBytes: 4096;
     maxHistoryPage: 200;
     maxPendingFrames: 100;
     heartbeatMs: 15000;
@@ -47,6 +48,13 @@ export interface ChatTransportAccess {
      * scopes the id to this conversation. Without it `?op=withdraw` is not supported. This handler never edits the inbox.
      */
     readonly abortSubmission?: (id: SubmissionId) => Promise<'aborted' | 'already_placed' | 'settled' | 'not_found'>;
+    /**
+     * Receive the screen context a browser sent with a submit (`context`, from `createRemoteChat({ requestContext })`), called after
+     * the request is validated and admitted and before `conversation.submit`. The value is a plain JSON object of at most
+     * `CHAT_TRANSPORT.maxContextBytes`; anything else is `400 invalid-request`. The host stores it by conversation id and renders
+     * it in `createPromptContext({ context })`; this handler keeps nothing. Without it the `context` field is ignored.
+     */
+    readonly requestContext?: (value: Readonly<Record<string, unknown>>) => void | Promise<void>;
     /** Refuse an effect call. Reading stays governed by `authenticate` and `project`. */
     readonly allow?: (operation: 'submit' | 'abort' | 'answer' | 'withdraw' | 'configure') => boolean | Promise<boolean>;
 }

package/dist/chat-transport.js

@@ -1,6 +1,6 @@
 import { RequestGuardError, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
 /** Wire protocol shared with the browser client in `@hachej/boring-ui-kit/remote-chat`. */
-export const CHAT_TRANSPORT = Object.freeze({ schema: 'boring.chat-transport', version: 1, maxRequestBytes: 8_388_608, maxHistoryPage: 200, maxPendingFrames: 100, heartbeatMs: 15_000 });
+export const CHAT_TRANSPORT = Object.freeze({ schema: 'boring.chat-transport', version: 1, maxRequestBytes: 8_388_608, maxContextBytes: 4096, maxHistoryPage: 200, maxPendingFrames: 100, heartbeatMs: 15_000 });
 /** `no-transform` keeps proxies from compressing or rewriting responses; the watch stream adds `x-accel-buffering: no` so nginx does not buffer it. */
 const headers = { 'cache-control': 'no-store, no-transform', 'x-content-type-options': 'nosniff' };
 const failure = (status, reason) => Response.json({ schema: CHAT_TRANSPORT.schema, version: CHAT_TRANSPORT.version, reason }, { status, headers });
@@ -12,6 +12,14 @@ function content(value) {
     return Array.isArray(value) && value.length > 0 && value.every(part => part !== null && typeof part === 'object'
         && ((part.type === 'text' && typeof part.text === 'string') || (part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string')));
 }
+/** The submit `context` field: absent, or a plain JSON object of at most `maxContextBytes` once serialized. */
+function contextValue(value) {
+    if (value === undefined)
+        return true;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return encoder.encode(JSON.stringify(value)).length <= CHAT_TRANSPORT.maxContextBytes;
+}
 async function body(request) {
     const value = await readJsonBody(request, CHAT_TRANSPORT.maxRequestBytes, request.signal);
     if (value === null || typeof value !== 'object' || Array.isArray(value))
@@ -207,7 +215,8 @@ export function createChatTransportHandler(options) {
             if (request.method === 'POST' && operation === 'submit') {
                 const input = await body(request);
                 if (typeof input['requestId'] !== 'string' || !input['requestId'] || !content(input['content'])
-                    || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string'))
+                    || (input['whenBusy'] !== undefined && typeof input['whenBusy'] !== 'string')
+                    || (access.requestContext && !contextValue(input['context'])))
                     return failure(400, 'invalid-request');
                 let prepared = input['content'];
                 if (access.prepareInput) {
@@ -218,6 +227,10 @@ export function createChatTransportHandler(options) {
                 }
                 if (!await allowed('submit') || access.revoked?.aborted)
                     return failure(403, 'not-authorized');
+                if (access.requestContext && input['context'] !== undefined)
+                    await access.requestContext(input['context']);
+                if (access.revoked?.aborted)
+                    return failure(403, 'not-authorized');
                 const submission = await conversation.submit({ type: 'input', requestId: input['requestId'], content: prepared,
                     ...(input['whenBusy'] === undefined ? {} : { whenBusy: input['whenBusy'] }) }, context);
                 return json({ submissionId: submission.id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -139,8 +139,8 @@
     "@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.3",
-    "@hachej/boring-ui-kit": "^0.2.3"
+    "@hachej/boring-files": "^0.2.4",
+    "@hachej/boring-ui-kit": "^0.2.4"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {