@hachej/boring-agent 0.4.29 → 0.4.30

package/README.md

@@ -56,6 +56,10 @@ Limits: a run is admitted against its hold, not stopped mid-run (no per-call fen
 
 ## Artifacts
 
+`present` also accepts exactly one host-owned task reference: `{ task: 'D-201' }` or `{ tasks: { filter: 'all' | 'mine' | 'waiting-on-me' } }`. These calls need no workspace. They return `{ kind: 'presented', artifact: { schema: 'boring.task', version: 1, type: 'task', title, subject } }`, with no file target, revision or task payload. The host authenticates and resolves `subject`; `mine` uses its authenticated person, never a model-supplied principal. `parsePresentedArtifact` accepts both file and task descriptors; the existing `parseArtifact` and `ArtifactDescriptor` stay file-only. Browser contracts are exported by `@hachej/boring-ui-kit/chat-view`.
+
+With `ack`, task presentation uses the same durable wait and outcomes as files. The page reports `{ kind: 'opened', instanceId, subject }` only after the exact authorized task or filtered list loads and mounts, or `{ kind: 'refused', reason }`. A different task, filter or file-shaped report is refused. This confirms a view, not task completion, consent, permission or a mutation. Without a mount report it remains `unconfirmed`. [`AmbientChat` host viewers](../../registry/README.md#host-task-viewers) receive `onShown`/`onFailed` through the second argument of `artifacts.open`; existing file calls and one-argument host openers remain valid.
+
 `createPresentTool({ workspace, resolveAccess?, maxBytes? })` from `@hachej/boring-agent/artifacts` returns the native `present(path)` tool (its workspace resolved per call like the guard's): the agent writes a workspace file with its ordinary file tools and presents it, and the chat shows a card that points at that file (`target`, the revision shown, no `id` or `ordinal`). The file's versions are the history of the workspace provider (`@hachej/boring-files/workspace`, whose `keep` retains the presented revision); a card of an older revision pins it and a card of the newest follows the file as it changes. The tool writes nothing and refuses files that are missing, not UTF-8 text or larger than 256 KiB. An opt-in `ack: { timeoutMs?, viewers? }` makes `present` wait until a page has mounted the presented revision: the page answers `{ kind: 'opened', instanceId, path, revision }` or `{ kind: 'refused', reason }` through the chat's `answer` (the transport's `?op=answer`), and the result carries `opened: true` with `viewer`, `opened: false` with `refused` (for example `closed by user`), `opened: 'unconfirmed'` after `timeoutMs` (default 15 s) or `opened: false, viewer: 'none'` at once when `viewers()` says no page watches the conversation. The wait is the durable wait of `ask_user` (`packages/agent/src/view-open.ts`, a conversation document keyed by the call); the deadline is stored, so a restart cannot extend it, and the first valid answer wins. Without `ack` the result is unchanged. `answerViewOpen` settles an answer; the host chains it with `answerUserQuestion` and `answerBrowserTask` in its `answer` handler. How to use it is in the tool's own description, so a host does not repeat it in its prompt: substantial output goes to a file that is then presented, short answers (and anything asked for in the chat) stay in the chat, and a revision re-reads the file, changes it at the same path and presents it again. A host adds only what is its own, such as what its HTML preview allows.
 
 ### A view that is not a document (a dashboard)

package/dist/artifacts.d.ts

@@ -3,6 +3,12 @@ import { Type } from '@earendil-works/pi-ai';
 import type { Context } from '@earendil-works/chord';
 import type { ResourceAccess, ResourceLocator } from '@hachej/boring-files';
 import type { WorkspaceBinding, WorkspaceResolver } from './workspaces.js';
+import type { TaskArtifactDescriptor } from './task-artifacts.js';
+export { createTaskArtifact, parseTaskArtifact, parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
+export type { TaskArtifactDescriptor, TaskSubject } from './task-artifacts.js';
+export type PresentedArtifact = ArtifactDescriptor | TaskArtifactDescriptor;
+/** Parse file or host-task presentation without treating a record as a workspace file. */
+export declare function parsePresentedArtifact(value: unknown): PresentedArtifact | undefined;
 import type { ViewOpenOptions } from './view-open.js';
 export { answerViewOpen, parseViewOpenAnswer, VIEW_OPEN_TIMEOUT_MS } from './view-open.js';
 export type { ViewOpenAnswer, ViewOpenOptions, ViewOpenOutcome } from './view-open.js';
@@ -57,6 +63,10 @@ export interface PresentToolOptions {
  * tools first. The card points at the file; the file's history (the provider's) is its list of versions. Nothing is written here.
  */
 export declare function createPresentTool(options?: PresentToolOptions): import("@earendil-works/pi-durable").ToolRegistration<Type.TObject<{
-    path: Type.TString;
+    path: Type.TOptional<Type.TString>;
+    task: Type.TOptional<Type.TString>;
+    tasks: Type.TOptional<Type.TObject<{
+        filter: Type.TUnion<[Type.TLiteral<"all">, Type.TLiteral<"mine">, Type.TLiteral<"waiting-on-me">]>;
+    }>>;
 }>, import("@earendil-works/chord").JsonValue>;
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.js

@@ -2,7 +2,11 @@ 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';
-import { PRESENT_TOOL, awaitViewOpen } from './view-open.js';
+import { createTaskArtifact, parseTaskArtifact, parseTaskSubject } from './task-artifacts.js';
+export { createTaskArtifact, parseTaskArtifact, parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
+/** Parse file or host-task presentation without treating a record as a workspace file. */
+export function parsePresentedArtifact(value) { return parseArtifact(value) ?? parseTaskArtifact(value); }
+import { PRESENT_TOOL, awaitTaskViewOpen, awaitViewOpen } from './view-open.js';
 export { answerViewOpen, parseViewOpenAnswer, VIEW_OPEN_TIMEOUT_MS } from './view-open.js';
 /*
  * Artifacts: substantial, self-contained content (a document, an HTML page, an SVG, code) that a chat shows as a card
@@ -100,14 +104,30 @@ export function createPresentTool(options = {}) {
         name: PRESENT_TOOL,
         // How to use it travels with the tool, so every host that offers `present` gets the same rules without repeating them in its prompt.
         description: [
+            'Show a host task with { task: "D-201" }, or a task list with { tasks: { filter: "all", "mine" or "waiting-on-me" } }. Tasks are host records, not workspace files; the host checks access when it opens them.',
             'Show a file of the workspace to the person in a side panel instead of pasting it in your reply.',
             'When the person asks for something substantial and self-contained (a report, document, HTML page, SVG image or program), write it to a file with the write tool, using a short descriptive path with the right extension (.md, .html, .svg with a viewBox, or the language\'s own), then call present with that path; never put that content in your reply. After present, reply with one or two short sentences and never repeat the content.',
             'Short answers stay in the chat, and so does anything the person asks to have in the chat or without tools or artifacts: then call no tool.',
             'To change, extend or fix something you presented: read the file again first (the person may have edited it; keep their changes), change it with edit (or write the whole new content) at the same path, never a second file, and call present again. If you do not remember the path, list the files.',
         ].join(' '),
-        parameters: Type.Object({ path: Type.String({ minLength: 1, maxLength: 512, description: 'The file path, relative to the workspace.' }) }, { additionalProperties: false }),
+        parameters: Type.Object({
+            path: Type.Optional(Type.String({ minLength: 1, maxLength: 512, description: 'A workspace file path. Supply exactly one of path, task or tasks.' })),
+            task: Type.Optional(Type.String({ minLength: 1, maxLength: 128, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*$', description: 'A host task id or number, such as D-201.' })),
+            tasks: Type.Optional(Type.Object({ filter: Type.Union([Type.Literal('all'), Type.Literal('mine'), Type.Literal('waiting-on-me')]) }, { additionalProperties: false })),
+        }, { additionalProperties: false }),
         replay: 'safe',
         execute: async (args, api, context) => {
+            if (Object.keys(args).length !== 1)
+                return reply({ kind: 'denied', reason: 'Supply exactly one of path, task or tasks' });
+            if (args.path === undefined) {
+                const subject = parseTaskSubject(args);
+                if (!subject)
+                    return reply({ kind: 'denied', reason: 'Invalid task reference' });
+                if (!options.ack)
+                    return reply({ kind: 'presented', artifact: createTaskArtifact(subject) });
+                const shown = await awaitTaskViewOpen(api, context, { tool: PRESENT_TOOL, subject }, options.ack);
+                return reply({ kind: 'presented', artifact: createTaskArtifact(shown.subject), ...viewFields(shown.outcome) });
+            }
             // 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' });

package/dist/task-artifacts.d.ts

@@ -0,0 +1,22 @@
+/** A host-owned task reference, not a file, execution task, permission or mutation. */
+export type TaskSubject = {
+    readonly task: string;
+} | {
+    readonly tasks: {
+        readonly filter: 'all' | 'mine' | 'waiting-on-me';
+    };
+};
+export interface TaskArtifactDescriptor {
+    readonly schema: 'boring.task';
+    readonly version: 1;
+    readonly type: 'task';
+    readonly title: string;
+    readonly subject: TaskSubject;
+}
+/** Strict, detached reference parsing; the host still authenticates and resolves the task. */
+export declare function parseTaskSubject(value: unknown): TaskSubject | undefined;
+/** The browser and server use the same exact subject identity for presentation acknowledgements. */
+export declare function taskSubjectKey(subject: TaskSubject): string;
+export declare function parseTaskArtifact(value: unknown): TaskArtifactDescriptor | undefined;
+export declare function createTaskArtifact(subject: TaskSubject): TaskArtifactDescriptor;
+//# sourceMappingURL=task-artifacts.d.ts.map

package/dist/task-artifacts.js

@@ -0,0 +1,34 @@
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const only = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+/** Strict, detached reference parsing; the host still authenticates and resolves the task. */
+export function parseTaskSubject(value) {
+    if (!object(value))
+        return undefined;
+    if (only(value, ['task']) && typeof value['task'] === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value['task']))
+        return { task: value['task'] };
+    const tasks = value['tasks'];
+    if (!only(value, ['tasks']) || !object(tasks) || !only(tasks, ['filter']))
+        return undefined;
+    const filter = tasks['filter'];
+    return filter === 'all' || filter === 'mine' || filter === 'waiting-on-me' ? { tasks: { filter } } : undefined;
+}
+/** The browser and server use the same exact subject identity for presentation acknowledgements. */
+export function taskSubjectKey(subject) {
+    return 'task' in subject ? JSON.stringify(['task', subject.task]) : JSON.stringify(['tasks', subject.tasks.filter]);
+}
+export function parseTaskArtifact(value) {
+    if (!object(value) || !only(value, ['schema', 'version', 'type', 'title', 'subject']))
+        return undefined;
+    if (value['schema'] !== 'boring.task' || value['version'] !== 1 || value['type'] !== 'task')
+        return undefined;
+    const title = value['title'], subject = parseTaskSubject(value['subject']);
+    if (typeof title !== 'string' || !title.trim() || title.length > 200 || !subject)
+        return undefined;
+    return { schema: 'boring.task', version: 1, type: 'task', title, subject };
+}
+export function createTaskArtifact(subject) {
+    const parsed = parseTaskSubject(subject);
+    if (!parsed)
+        throw new TypeError('Invalid task subject');
+    return { schema: 'boring.task', version: 1, type: 'task', title: 'task' in parsed ? parsed.task : parsed.tasks.filter === 'mine' ? 'My requests' : parsed.tasks.filter === 'waiting-on-me' ? 'Waiting on me' : 'Tasks', subject: parsed };
+}

package/dist/view-open.d.ts

@@ -1,6 +1,7 @@
 import type { Conversation, ToolExecutionApi } from '@earendil-works/pi-durable';
 import type { Context } from '@earendil-works/chord';
 import type { AskUserAnswer } from './ask-user.js';
+import type { TaskSubject } from './task-artifacts.js';
 /** How long a view may take to be confirmed by a page before the result says `unconfirmed` (a UI ack, not a person's decision). */
 export declare const VIEW_OPEN_TIMEOUT_MS = 15000;
 /** The tool whose calls the view-open record belongs to, unless a host renamed `present`. */
@@ -11,6 +12,10 @@ export type ViewOpenAnswer = {
     readonly instanceId: string;
     readonly path: string;
     readonly revision: string;
+} | {
+    readonly kind: 'opened';
+    readonly instanceId: string;
+    readonly subject: TaskSubject;
 } | {
     readonly kind: 'refused';
     readonly reason: string;
@@ -50,6 +55,14 @@ export declare function awaitViewOpen(api: ToolExecutionApi, context: Context, v
     readonly outcome: ViewOpenOutcome;
     readonly revision: string;
 }>;
+/** A record viewer confirms the exact task or filter, never a fabricated file revision. */
+export declare function awaitTaskViewOpen(api: ToolExecutionApi, context: Context, view: {
+    readonly tool: string;
+    readonly subject: TaskSubject;
+}, options?: ViewOpenOptions): Promise<{
+    readonly outcome: ViewOpenOutcome;
+    readonly subject: TaskSubject;
+}>;
 /**
  * Settles a pending view with the page's answer (JSON text) after the host authenticated the person. `id` is the answer ID of the
  * call (`[assistantEntryId, callId]`, or a raw call ID used by one task). An `opened` answer must name the path and revision the

package/dist/view-open.js

@@ -6,6 +6,7 @@
 import { defineDocFamily } from '@earendil-works/pi-durable';
 import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
 import { AmbiguousCall, UnknownCall, callBinding, ownBindingKey, waitForDocument } from './durable-wait.js';
+import { parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
 /** How long a view may take to be confirmed by a page before the result says `unconfirmed` (a UI ack, not a person's decision). */
 export const VIEW_OPEN_TIMEOUT_MS = 15_000;
 /** The tool whose calls the view-open record belongs to, unless a host renamed `present`. */
@@ -32,6 +33,12 @@ export function parseViewOpenAnswer(value) {
             return undefined;
         return { kind: 'opened', instanceId, path, revision };
     }
+    if (value['kind'] === 'opened' && Object.keys(value).every(key => ['kind', 'instanceId', 'subject'].includes(key))) {
+        const instanceId = value['instanceId'], subject = parseTaskSubject(value['subject']);
+        if (typeof instanceId !== 'string' || !instanceId || instanceId.length > MAX_ID || !subject)
+            return undefined;
+        return { kind: 'opened', instanceId, subject };
+    }
     if (value['kind'] === 'refused' && Object.keys(value).every(key => ['kind', 'reason'].includes(key))) {
         const { reason } = value;
         if (typeof reason !== 'string' || !reason || reason.length > MAX_REASON)
@@ -47,16 +54,29 @@ export function parseViewOpenAnswer(value) {
  * current one, so the result never pairs a new file revision with an old acknowledgement.
  */
 export async function awaitViewOpen(api, context, view, options = {}) {
+    const result = await awaitPresentation(api, context, view, options);
+    if (!('revision' in result.binding))
+        throw new Error('The presentation belongs to a task reference');
+    return { outcome: result.outcome, revision: result.binding.revision };
+}
+/** A record viewer confirms the exact task or filter, never a fabricated file revision. */
+export async function awaitTaskViewOpen(api, context, view, options = {}) {
+    const result = await awaitPresentation(api, context, view, options);
+    if (!('subject' in result.binding))
+        throw new Error('The presentation belongs to a file');
+    return { outcome: result.outcome, subject: result.binding.subject };
+}
+async function awaitPresentation(api, context, view, options) {
     const timeoutMs = options.timeoutMs ?? VIEW_OPEN_TIMEOUT_MS;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
         throw new TypeError('The view-open timeout must be a positive integer of milliseconds');
     if (options.viewers && !(await options.viewers(api, context)))
-        return { outcome: { kind: 'none' }, revision: view.revision };
+        return { outcome: { kind: 'none' }, binding: view };
     const { key, startedAt, duration } = await api.commit(async (tx) => {
         const key = await ownBindingKey(tx, api);
         const document = await tx.doc(documents, api.conversationId, key, null);
         if (!document.view)
-            document.view = { tool: view.tool, taskId: api.taskId, path: view.path, revision: view.revision, startedAt: Date.now(), timeoutMs, state: { kind: 'pending' } };
+            document.view = { ...view, taskId: api.taskId, startedAt: Date.now(), timeoutMs, state: { kind: 'pending' } };
         if (document.view.taskId !== api.taskId)
             throw new Error('View-open identity belongs to another task');
         return { key, startedAt: document.view.startedAt, duration: document.view.timeoutMs };
@@ -73,13 +93,13 @@ export async function awaitViewOpen(api, context, view, options = {}) {
             document.view.state = { kind: 'cancelled' };
     }, 'View open', { at: startedAt + duration, expire });
     const state = final?.view?.state;
-    const revision = final?.view?.revision ?? view.revision;
+    const binding = final?.view ?? view;
     if (state?.kind === 'opened')
-        return { outcome: { kind: 'opened', viewer: state.viewer }, revision };
+        return { outcome: { kind: 'opened', viewer: state.viewer }, binding };
     if (state?.kind === 'refused')
-        return { outcome: { kind: 'refused', reason: state.reason }, revision };
+        return { outcome: { kind: 'refused', reason: state.reason }, binding };
     if (state?.kind === 'unconfirmed')
-        return { outcome: { kind: 'unconfirmed', timeoutMs: duration }, revision };
+        return { outcome: { kind: 'unconfirmed', timeoutMs: duration }, binding };
     throw new Error('View open cancelled');
 }
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
@@ -104,7 +124,7 @@ export async function answerViewOpen(conversation, id, answer, options = {}) {
     }
     const parsed = parseViewOpenAnswer(value);
     if (!parsed)
-        return { kind: 'denied', reason: 'The answer must be { kind: "opened", instanceId, path, revision } or { kind: "refused", reason }' };
+        return { kind: 'denied', reason: 'The answer must name an opened file revision or task subject with instanceId, or be { kind: "refused", reason }' };
     const next = parsed.kind === 'opened' ? { kind: 'opened', viewer: parsed.instanceId } : { kind: 'refused', reason: parsed.reason };
     try {
         return await conversation.commit(async (tx) => {
@@ -119,6 +139,11 @@ export async function answerViewOpen(conversation, id, answer, options = {}) {
             const record = document.view;
             if (record.taskId !== task.id)
                 return { kind: 'conflict', reason: 'The view belongs to another task' };
+            if (parsed.kind === 'opened' && ('subject' in parsed
+                ? !('subject' in record) || taskSubjectKey(parsed.subject) !== taskSubjectKey(record.subject)
+                : !('path' in record) || parsed.path.replace(/^\.\//, '') !== record.path || parsed.revision !== record.revision)) {
+                return { kind: 'denied', reason: 'The acknowledgement names another subject or revision than the one presented' };
+            }
             if (record.state.kind !== 'pending')
                 return same(record.state, next) ? { kind: 'answered' } : { kind: 'conflict', reason: 'The view was already decided' };
             if (task.abortRequested || task.state.status === 'terminal') {
@@ -129,9 +154,6 @@ export async function answerViewOpen(conversation, id, answer, options = {}) {
                 record.state = { kind: 'unconfirmed' };
                 return { kind: 'conflict', reason: 'The view was not confirmed in time' };
             }
-            if (parsed.kind === 'opened' && (parsed.path.replace(/^\.\//, '') !== record.path || parsed.revision !== record.revision)) {
-                return { kind: 'denied', reason: 'The acknowledgement names another file or revision than the one presented' };
-            }
             record.state = next;
             return { kind: 'answered' };
         }, options.context ?? BACKGROUND_CONTEXT);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.4.29",
+  "version": "0.4.30",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -180,8 +180,8 @@
     "@earendil-works/pi-durable": "~1.4.0",
     "@earendil-works/pi-ai": "~1.4.0",
     "@earendil-works/chord": "~1.4.0",
-    "@hachej/boring-files": "^0.4.29",
-    "@hachej/boring-ui-kit": "^0.4.29",
+    "@hachej/boring-files": "^0.4.30",
+    "@hachej/boring-ui-kit": "^0.4.30",
     "typebox": "1.3.27",
     "xlsx": "^0.20.3"
   },