@hachej/boring-agent 0.3.2 → 0.4.0

package/README.md

@@ -134,7 +134,7 @@ 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`.
+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. With `useRemoteChat` the context is the `requestContext` value as it is (`name`, `params`: a host written before placement keeps working) plus `placement` (`docked` or `floating`), reported by `PiChat` / `AmbientChat`; `PiChat` takes a `placement` prop for a host that floats it, as the `AgentLayer` does. `renderRequestContext(value)` (from `@hachej/boring-agent/prompt-context`) turns it into the agent's role and the screen for `createPromptContext`; placement changes behaviour, never authority (see [PAGE-TOOLS.md](../../docs/architecture/PAGE-TOOLS.md)). Tests: `test/packages/agent-chat-transport-context.test.mjs`, `test/packages/ui-remote-chat-context.test.mjs`, `test/packages/agent-prompt-context.test.mjs`, `test/contracts/chat-placement.test.mjs`, `test/contracts/chat-placement-registry.test.mjs`.
 
 ## Native questions
 
@@ -160,9 +160,9 @@ The native delivery task is version 2. Existing version 1 records migrate with e
 
 `resolveAccess` may return a Promise. When recovery reads the original actor from native producer input, pass that already-authenticated access as the sixth admission argument: `admit(tx, createProducer, target, taskOptions, context, access)`. Admission captures its identity before awaiting producer creation. Publication still resolves current access and compares the original identity. Omitting the sixth argument preserves resolution during admission; such a resolver must not read the same Harness or call `tx.task` after producer writes. Native transactions reject table reads after their first write. Explicit access is trusted host input, not authentication or a grant. Resolved credential fields are copied before digest, memo and provider awaits.
 
-Run `node examples/background-document.mjs` after building for fictional question, native producer and document delivery without a model, browser or shell. The example resolves a fixed fictional answer in trusted host code; it is not an authenticated remote human journey.
+Run `node fixtures/background-document.mjs` after building for fictional question, native producer and document delivery without a model, browser or shell. The example resolves a fixed fictional answer in trusted host code; it is not an authenticated remote human journey.
 
-Import interfaces with `import type`. See [scaffold guide](../../docs/contracts/SCAFFOLD.md), [native examples](../../examples/native-compositions.ts) and [implementation evidence](../../docs/implementation/PARTIAL.md).
+Import interfaces with `import type`. See [scaffold guide](../../docs/contracts/SCAFFOLD.md), [native examples](../../fixtures/native-compositions.ts) and [implementation evidence](../../docs/implementation/PARTIAL.md).
 
 ## Authorized conversation text
 
@@ -182,7 +182,7 @@ The adapter keeps the last bounded delivered window and no update queue. A slow
 
 TLS, cookies, CORS, socket/proxy lifecycle, browser presentation and deployment authentication remain host qualifications. Public projection tests exercise actual native watches through in-process Fetch/Web Streams. `npm run test:projection-consumer` installs the agent archive without files/UI/execution packages, checks strict declarations, repeats the tests and builds the receiver for a browser. It requires the pinned registry archives in a writable npm cache.
 
-Run `node examples/conversation-projection.mjs` after building for a fictional authenticated stream and idle revocation demonstration.
+Run `node fixtures/conversation-projection.mjs` after building for a fictional authenticated stream and idle revocation demonstration.
 
 ## Authenticated question responses
 
@@ -194,7 +194,7 @@ Responses expose the narrow native decision, with `no-store` headers. An observe
 
 `test/packages/agent-question-response.test.mjs` exercises real native transactions through Fetch requests, including duplicate answers, identity/policy refusal, streamed byte limits, unacknowledged source cancellation and lost response recovery. `npm run test:question-consumer` repeats these scenarios from the installed agent and files tarballs without UI/execution packages; the handler reads bodies through `@hachej/boring-files/request-guard`, so install `@hachej/boring-files` (an optional peer) with this subpath. Set `npm_config_cache` to a writable cache of the pinned dependencies. Socket/browser authentication, remote inbox presentation and human identity-provider integration remain unqualified.
 
-The strict TypeScript consumer recipe additionally installs `@modelcontextprotocol/sdk@1.32.0`. Pinned Pi model declarations transitively load `@google/genai`, whose declarations reference that optional SDK. This dependency is needed for this `skipLibCheck: false` recipe even though the question runtime does not call MCP. The consumer does not establish strict checking with only the agent's declared peers installed.
+The strict TypeScript consumer recipe additionally installs `@modelcontextprotocol/sdk@1.32.1`. Pinned Pi model declarations transitively load `@google/genai`, whose declarations reference that optional SDK. This dependency is needed for this `skipLibCheck: false` recipe even though the question runtime does not call MCP. The consumer does not establish strict checking with only the agent's declared peers installed.
 
 `@hachej/boring-agent/git` exports `createGitTool(repository?)`. Register this ordinary native tool with the same host-created `@hachej/boring-files/git` repository used by Bash or direct callers, or without one: each call then uses the `repository` of its own workspace binding (the one attached to the call's env, see [Workspace per call](#workspace-per-call)), so one tool serves a repository per person. It exposes the local service operations and preserves native ToolTask execution. The tool is always unsafe to replay because working Git has no publication receipts. The repository's host-bound authorization applies on every call. No environment or shell is mandatory for a file-only repository binding.
 
@@ -222,7 +222,7 @@ Native configuration retains tool names. A later registry replacement or native
 
 The resource must be UTF-8 `application/json`, optionally with `charset=utf-8`. The default accepted size is 65,536 bytes; `maxBytes` accepts integers from 1 to 1,048,576. This limits accepted bytes after the reader returns, not provider allocation. The loader preserves borrowed tool/provider ownership and checks an optional abort signal after awaited operations; it cannot interrupt a noncooperative reader or resolver.
 
-Run `node examples/agent-definitions.mjs` after building for a fictional definition, explicit native configuration and real document publication. `npm run test:definitions-consumer` installs files/agent archives with pinned registry dependencies, checks strict declarations and repeats exact-read, native publication, reopen and registry-replacement tests. Like the question consumer, this strict fixture explicitly installs the pinned optional model SDK declaration dependencies.
+Run `node fixtures/agent-definitions.mjs` after building for a fictional definition, explicit native configuration and real document publication. `npm run test:definitions-consumer` installs files/agent archives with pinned registry dependencies, checks strict declarations and repeats exact-read, native publication, reopen and registry-replacement tests. Like the question consumer, this strict fixture explicitly installs the pinned optional model SDK declaration dependencies.
 
 ## Structured output and native tool evidence
 

package/dist/chat-transport.js

@@ -33,8 +33,8 @@ async function body(request) {
  */
 function reads(conversation, context, project) {
     return {
-        async entries(limit, cursor) {
-            const page = await conversation.entries({}, limit, cursor, context);
+        async entries(query, limit, cursor) {
+            const page = await conversation.entries(query, limit, cursor, context);
             if (!project)
                 return page;
             const record = await conversation.commit(tx => tx.conversation(conversation.id), context);
@@ -207,7 +207,19 @@ export function createChatTransportHandler(options) {
                         return failure(400, 'invalid-request');
                     }
                 }
-                const page = await read.entries(limit, cursor);
+                const entryId = (encoded) => {
+                    if (encoded === null)
+                        return undefined;
+                    const value = Number(encoded);
+                    if (!Number.isSafeInteger(value) || value < 1)
+                        throw new RequestGuardError(400, 'Invalid native entry bound');
+                    return value;
+                };
+                const maxEntryId = entryId(params.get('maxEntryId')), minEntryId = entryId(params.get('minEntryId'));
+                const order = params.get('order');
+                if (order !== null && order !== 'ascending' && order !== 'descending')
+                    return failure(400, 'invalid-request');
+                const page = await read.entries({ ...(maxEntryId === undefined ? {} : { maxEntryId }), ...(minEntryId === undefined ? {} : { minEntryId }), ...(order === null ? {} : { order }) }, limit, cursor);
                 if (access.revoked?.aborted)
                     return failure(403, 'not-authorized');
                 return json({ page });

package/dist/prompt-context.d.ts

@@ -22,4 +22,13 @@ export interface PromptContextOptions {
  */
 export declare function withRequestContext(messages: readonly Message[], text: string, tag?: string): Message[];
 export declare function createPromptContext(options: PromptContextOptions): Extension;
+/**
+ * The text for the browser's request context: the screen's `{ name, params }` with `placement` beside them, as `useRemoteChat` sends it
+ * (an older client sends only `{ name, params }`, which still renders; a `{ screen }` wrapper is read too). The host calls this in
+ * `createPromptContext({ context })` on the value it stored by conversation id. `placement` is `docked` or `floating` and picks the
+ * agent's role. Both are advisory text from the browser: placement changes behaviour and never authority (a docked agent writes no
+ * more than a floating one), and anything else in the value is ignored.
+ * See docs/architecture/PAGE-TOOLS.md (PLACE-1..3).
+ */
+export declare function renderRequestContext(value: unknown): string | undefined;
 //# sourceMappingURL=prompt-context.d.ts.map

package/dist/prompt-context.js

@@ -36,3 +36,29 @@ export function createPromptContext(options) {
             })],
     });
 }
+const ROLES = {
+    docked: 'The chat is docked beside the page: you lead. Open the pages, records and files that answer the question in the viewer, and say what you opened.',
+    floating: 'The chat floats over the page: the person leads. Do not move the page unless asked; answer briefly about what is on screen and suggest where to go.',
+};
+/**
+ * The text for the browser's request context: the screen's `{ name, params }` with `placement` beside them, as `useRemoteChat` sends it
+ * (an older client sends only `{ name, params }`, which still renders; a `{ screen }` wrapper is read too). The host calls this in
+ * `createPromptContext({ context })` on the value it stored by conversation id. `placement` is `docked` or `floating` and picks the
+ * agent's role. Both are advisory text from the browser: placement changes behaviour and never authority (a docked agent writes no
+ * more than a floating one), and anything else in the value is ignored.
+ * See docs/architecture/PAGE-TOOLS.md (PLACE-1..3).
+ */
+export function renderRequestContext(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { placement, screen } = value;
+    const lines = [];
+    if (placement === 'docked' || placement === 'floating')
+        lines.push(`Placement: ${placement}. ${ROLES[placement]}`);
+    const shown = typeof screen === 'object' && screen !== null ? screen : value;
+    if (typeof shown.name === 'string') {
+        const { name, params } = shown;
+        lines.push(`The person is looking at: ${name}${params && typeof params === 'object' && Object.keys(params).length ? ` ${JSON.stringify(params)}` : ''}`);
+    }
+    return lines.length ? lines.join('\n') : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -139,8 +139,8 @@
     "@earendil-works/pi-durable": "~1.2.0",
     "@earendil-works/pi-ai": "~1.2.0",
     "@earendil-works/chord": "~1.2.0",
-    "@hachej/boring-files": "^0.3.2",
-    "@hachej/boring-ui-kit": "^0.3.2"
+    "@hachej/boring-files": "^0.4.0",
+    "@hachej/boring-ui-kit": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@hachej/boring-files": {