@hachej/boring-agent 0.1.111 → 0.2.1

package/dist/file-guard.js

@@ -0,0 +1,177 @@
+import { defineDoc, defineExtension, wrapTool } from '@earendil-works/pi-durable';
+import { FileError, err, getOrThrow, ok } from '@earendil-works/pi-durable/env';
+import { createEditTool, createReadTool, createWriteTool } from '@earendil-works/pi-durable/tools';
+import { asWorkspaceResolver, decorate, workspaceFor } from './workspaces.js';
+/** Conversation document: workspace and path (relative to the workspace root; see `baselineKey`) to the revision this conversation last read or wrote. */
+export const lastReadRevisions = defineDoc({
+    kind: 'boring.files.last-read', version: 1, scope: 'conversation', history: 'latest', fork: 'initial',
+    initial: () => ({ revisions: {} }),
+});
+/** The baseline key of `path` in `workspace` (its `id`, or its provider id): `<workspace>:<path>`. */
+export const baselineKey = (workspace, path) => `${workspace.id ?? workspace.files.providerId}:${path}`;
+/** The revision this conversation last read or wrote under `key` (see `baselineKey`), or undefined. Also what host tools over workspace files (such as the canvas tools) check. */
+export const lastReadRevision = async (api, key, context) => (await api.snapshot(lastReadRevisions, api.conversationId, context))?.revisions[key];
+/** Record `revision` as the conversation's baseline under `key` (see `baselineKey`), durably. */
+export const recordRevision = (api, key, revision, context) => api.commit(async (tx) => {
+    const doc = await tx.doc(lastReadRevisions, api.conversationId);
+    doc.revisions[key] = revision;
+}, context);
+const refusal = (text) => ({ content: [{ type: 'text', text }], isError: true });
+// The same normalisation as Pi's tool paths: a leading "@" and special spaces.
+const normalised = (path) => { const spaced = path.replace(/[  -   　]/g, ' '); return spaced.startsWith('@') ? spaced.slice(1) : spaced; };
+/** `path` as the call's env names it, and relative to `root`, or undefined when it is not lexically inside `root` (or the call has no env). Pi's path normalisation applies. */
+export async function workspaceRelative(api, root, path, context) {
+    if (api.env === undefined)
+        return undefined;
+    const absolute = getOrThrow(await api.env.absolutePath(normalised(path), context));
+    return absolute.startsWith(`${root}/`) ? { path: absolute.slice(root.length + 1), absolute } : undefined;
+}
+/**
+ * Whether `absolute` really lies inside `root` once links are resolved, through the env's own `canonicalPath`. A path that does not
+ * exist yet is judged by its deepest existing ancestor, so a link directory cannot lead a new file out. Any other failure to resolve
+ * is a refusal: the guard fails closed.
+ */
+async function contained(env, root, absolute, context) {
+    if (env === undefined)
+        return false;
+    const realRoot = await env.canonicalPath(root, context);
+    if (!realRoot.ok)
+        return false;
+    const base = realRoot.value.replace(/\/+$/, '');
+    let candidate = absolute, rest = '';
+    for (;;) {
+        const real = await env.canonicalPath(candidate, context);
+        if (real.ok) {
+            const resolved = `${real.value.replace(/\/+$/, '')}${rest}`;
+            return resolved === base || resolved.startsWith(`${base}/`);
+        }
+        if (real.error.code !== 'not_found')
+            return false;
+        // A dangling link resolves to nothing, but a write through it would create its target: refuse it, wherever it is.
+        const link = await env.fileInfo(candidate, context);
+        // Only `not_found` proves nothing is there; a lost or failed answer could hide a link, so it refuses too.
+        if (link.ok ? link.value.kind === 'symlink' : link.error.code !== 'not_found')
+            return false;
+        const cut = candidate.lastIndexOf('/');
+        if (cut <= 0)
+            return false;
+        rest = `${candidate.slice(cut)}${rest}`;
+        candidate = candidate.slice(0, cut);
+    }
+}
+export const ONE_PATH = new Set(['readTextFile', 'openTextLineReader', 'readTextLines', 'readBinaryFile', 'openBinaryReader', 'writeFile', 'appendFile', 'truncateFile', 'flushFile', 'fileInfo', 'listDir', 'openDirReader', 'createDir', 'remove', 'canonicalPath']);
+/**
+ * `env` as the native `read`, `write` and `edit` must see it: every operation that opens, changes or lists a path first re-checks the
+ * path it is ABOUT to touch (links resolved, like `contained`) and refuses outside `root` with a typed `permission_denied`. The check
+ * is on the path Pi actually opens, so a fallback spelling Pi picks after the provider's check (NFD, curly apostrophe) is judged as
+ * itself. `exists` answers false for a path outside, so Pi's fallback loop moves on instead of revealing it. A Pi extension point
+ * (`ExecutionEnv` decorator), public API only. Residual: a symlink swapped between this check and the OS `open` is not closable from
+ * here; that boundary is the host's isolation (an isolated worker env), not this guard.
+ */
+export function confinedEnv(env, root) {
+    const denied = (path) => err(new FileError('permission_denied', `Refused: ${path} is outside the workspace.`, path));
+    const inside = (path, context) => contained(env, root, path, context);
+    return decorate(env, new Proxy(env, {
+        get(target, property) {
+            const member = Reflect.get(target, property, target);
+            if (typeof member !== 'function')
+                return member;
+            const method = member.bind(target);
+            if (typeof property !== 'string')
+                return method;
+            if (ONE_PATH.has(property))
+                return async (path, ...rest) => await inside(path, rest[rest.length - 1]) ? method(path, ...rest) : denied(path);
+            if (property === 'renameFile')
+                return async (from, to, context) => await inside(from, context) && await inside(to, context) ? method(from, to, context) : denied(`${from} -> ${to}`);
+            if (property === 'exists')
+                return async (path, context) => await inside(path, context) ? method(path, context) : ok(false);
+            return method;
+        },
+    }));
+}
+/** The guard as a native extension. Select it after the extension(s) that register `read`, `write` and `edit`. */
+export function createFileGuard(options = {}) {
+    const resolver = asWorkspaceResolver(options.workspace);
+    async function observeIn(files, path, access) {
+        const read = await files.read({ target: { resource: { providerId: files.providerId, path }, view: { kind: 'published' } }, revision: { kind: 'latest' } }, access);
+        if (read.kind === 'available')
+            return { kind: 'file', revision: read.snapshot.ref.revision };
+        if (read.kind === 'missing')
+            return { kind: 'missing' };
+        return { kind: 'refused', reason: read.reason };
+    }
+    function guarded(tool, mode) {
+        const execute = async (args, api, context) => {
+            const resolved = await workspaceFor(resolver, api, context);
+            if ('refused' in resolved)
+                return refusal(`Refused: ${resolved.refused}`);
+            const { binding } = resolved;
+            // The native tool gets the env decorated to re-check what it actually opens (see `confinedEnv`); the guard's own checks use the raw one.
+            const run = () => tool.execute(args, api.env === undefined ? api : Object.create(api, { env: { value: confinedEnv(api.env, binding.root.replace(/\/+$/, '')), enumerable: true } }), context);
+            const { files } = binding;
+            const root = binding.root.replace(/\/+$/, '');
+            const granted = options.resolveAccess ? await options.resolveAccess(api, context) : binding.access;
+            if (granted === undefined)
+                return refusal('Refused: the host gave no access for this workspace.');
+            const access = { ...granted };
+            const observe = (path) => observeIn(files, path, access);
+            const located = await workspaceRelative(api, root, args.path, context);
+            if (located === undefined || !await contained(api.env, root, located.absolute, context))
+                return refusal(`Refused: ${args.path} is outside the workspace.`);
+            const { path } = located;
+            const key = baselineKey(binding, path);
+            return files.queue.run(async () => {
+                const before = await observe(path);
+                if (mode === 'read') {
+                    if (before.kind === 'refused')
+                        return refusal(`Refused: ${path} cannot be read here (${before.reason}).`);
+                    // Pi's read falls back to other spellings of a missing path (NFD, a curly apostrophe, a narrow space before AM/PM). The
+                    // provider and the containment check only vouch for this spelling, so a missing one is refused here and never delegated.
+                    if (before.kind === 'missing')
+                        return refusal(`Refused: ${path} does not exist in the workspace.`);
+                    const result = await run();
+                    if (result.isError || before.kind !== 'file')
+                        return result;
+                    // Record only the bytes the model saw: a change during the call (a shell) leaves the baseline alone.
+                    const after = await observe(path);
+                    if (after.kind === 'file' && after.revision === before.revision)
+                        await recordRevision(api, key, after.revision, context);
+                    return result;
+                }
+                if (before.kind === 'refused')
+                    return refusal(`Refused: ${path} cannot be changed here (${before.reason}).`);
+                if (mode === 'edit' && before.kind === 'missing')
+                    return refusal(`Refused: ${path} does not exist in the workspace.`);
+                if (before.kind === 'file') {
+                    const known = await lastReadRevision(api, key, context);
+                    if (known === undefined)
+                        return refusal(`Refused: ${path} already exists and you have not read it in this conversation. Read it with the read tool, then make your change.`);
+                    if (known !== before.revision)
+                        return refusal(`Refused: ${path} changed since you last read it (the person or another process saved it). Read it again with the read tool, then redo your change on top of what is there now.`);
+                }
+                // Ruling 2: an agent write is observed (history, change event), never receipted. History keeps the replaced bytes too, so
+                // they are read now, before the tool overwrites them, unless that revision is already retained.
+                const preimage = before.kind === 'file' && !files.history(path).includes(before.revision) ? await files.read({ target: { resource: { providerId: files.providerId, path }, view: { kind: 'published' } }, revision: { kind: 'exact', value: before.revision } }, access) : undefined;
+                const result = await run();
+                if (!result.isError) {
+                    const after = await observe(path);
+                    if (after.kind === 'file') {
+                        await recordRevision(api, key, after.revision, context);
+                        // Not through `files.queue`: this already runs inside it. A failed history write never turns the done write into an error.
+                        await files.record({ path, before: preimage?.kind === 'available' ? { revision: preimage.snapshot.ref.revision, bytes: preimage.snapshot.bytes } : null, after: after.revision, source: 'agent', conversationId: String(api.conversationId) }, access).catch(() => undefined);
+                    }
+                }
+                return result;
+            });
+        };
+        return { ...tool, execute };
+    }
+    return defineExtension({
+        name: options.name ?? 'boring.files.guard',
+        wraps: [
+            wrapTool(createReadTool(), tool => guarded(tool, 'read')),
+            wrapTool(createWriteTool(), tool => guarded(tool, 'write')),
+            wrapTool(createEditTool(), tool => guarded(tool, 'edit')),
+        ],
+    });
+}

package/dist/file-types.d.ts

@@ -0,0 +1,17 @@
+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.
+ */
+export declare function mediaTypeFor(path: string, kind: FileKind, provided: string | undefined, head?: Uint8Array): string;
+//# sourceMappingURL=file-types.d.ts.map

package/dist/file-types.js

@@ -0,0 +1,95 @@
+/*
+ * 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`.
+ *
+ *  - `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).
+ *  - `archive`: a container nothing here opens.
+ *  - `binary`: any other file with a NUL byte.
+ *
+ * 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.
+ */
+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 },
+};
+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; };
+/** 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]))
+        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')
+        return 'image';
+    if (startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]))
+        return OFFICE.includes(extension) ? 'office' : 'archive';
+    if (startsWith(bytes, [0xd0, 0xcf, 0x11, 0xe0]))
+        return 'office';
+    return undefined;
+}
+/** 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 function fileKind(path, head) {
+    const extension = extensionOf(path);
+    const named = BY_EXTENSION.get(extension);
+    if (head !== undefined) {
+        const magic = kindByMagic(head, extension);
+        if (magic !== undefined)
+            return magic;
+        if (named === undefined || named === 'text')
+            return head.includes(0) ? 'binary' : 'text';
+    }
+    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);
+    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 generic = !provided || provided === 'application/octet-stream' || provided.startsWith('text/') || provided === 'application/zip';
+    if (!generic)
+        return provided;
+    return table ?? provided ?? 'application/octet-stream';
+}

package/dist/gateway-provider.d.ts

@@ -0,0 +1,24 @@
+import { type Provider } from '@earendil-works/pi-ai/models';
+/** The provider id gateway models carry unless the host names another. */
+export declare const GATEWAY_PROVIDER = "boring-gateway";
+/** A model the gateway allows, by its gateway id (the host maps it to an upstream model). */
+export interface GatewayModel {
+    readonly id: string;
+    readonly name?: string;
+    readonly contextWindow?: number;
+    /** Requested output ceiling; the gateway clamps it to the person's budget either way. */
+    readonly maxTokens?: number;
+    readonly input?: readonly ('text' | 'image')[];
+}
+export interface GatewayProviderOptions {
+    /** The gateway root: `/api/llm` (resolved against the page) or an absolute URL. Requests go to `<baseUrl>/v1/...` only. */
+    readonly baseUrl: string;
+    readonly models: readonly (string | GatewayModel)[];
+    /** The app session as request headers (for example `{ authorization: 'Bearer <session>' }`), read on every request. */
+    readonly getAuth: () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+    readonly id?: string;
+    readonly name?: string;
+}
+/** `models.setProvider(gatewayProvider({ baseUrl: '/api/llm', models: ['fernhill-preview'], getAuth }))`, then any Pi model call. */
+export declare function gatewayProvider(options: GatewayProviderOptions): Provider<'openai-completions'>;
+//# sourceMappingURL=gateway-provider.d.ts.map

package/dist/gateway-provider.js

@@ -0,0 +1,42 @@
+// @hachej/boring-agent/gateway-provider: a native Pi provider whose models are served by a Boring model gateway
+// (`@hachej/boring-agent/model-gateway` on the host, or a shared gateway service with the same API). Browser-safe: it knows only the
+// gateway's base URL and the app session headers; it holds no model key and reads no environment. The wire is Pi's own
+// `openai-completions` implementation pointed at `<baseUrl>/v1`, so streaming, tools and usage are native Pi behavior.
+// Self-contained on purpose (ARCHITECTURE.json pathRules forbid its relative and node imports).
+import { createProvider } from '@earendil-works/pi-ai/models';
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy';
+/** The provider id gateway models carry unless the host names another. */
+export const GATEWAY_PROVIDER = 'boring-gateway';
+function absolute(baseUrl) {
+    const page = globalThis.location?.href;
+    let url;
+    try {
+        url = page ? new URL(baseUrl, page) : new URL(baseUrl);
+    }
+    catch {
+        throw new TypeError('gatewayProvider needs an absolute baseUrl outside a page');
+    }
+    return `${url.origin}${url.pathname.replace(/\/+$/, '')}/v1`;
+}
+/** `models.setProvider(gatewayProvider({ baseUrl: '/api/llm', models: ['fernhill-preview'], getAuth }))`, then any Pi model call. */
+export function gatewayProvider(options) {
+    if (typeof options.getAuth !== 'function')
+        throw new TypeError('gatewayProvider needs getAuth()');
+    const id = options.id ?? GATEWAY_PROVIDER;
+    const baseUrl = absolute(options.baseUrl);
+    const models = options.models.map(entry => {
+        const model = typeof entry === 'string' ? { id: entry } : entry;
+        return {
+            id: model.id, name: model.name ?? model.id, api: 'openai-completions', provider: id, baseUrl, reasoning: false,
+            input: [...(model.input ?? ['text'])], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: model.contextWindow ?? 128_000, maxTokens: model.maxTokens ?? 4096,
+            // The gateway speaks plain chat completions: no stored responses, system prompts as `system`, usage in the stream.
+            compat: { supportsStore: false, supportsDeveloperRole: false, supportsReasoningEffort: false, supportsUsageInStreaming: true, maxTokensField: 'max_completion_tokens' },
+        };
+    });
+    return createProvider({
+        id, name: options.name ?? 'Boring model gateway', baseUrl, models, api: openAICompletionsApi(),
+        // The app session is the only credential: no API key exists on this side.
+        auth: { apiKey: { name: 'App session', resolve: async () => ({ auth: { headers: { ...(await options.getAuth()) } }, source: 'app session' }) } },
+    });
+}

package/dist/git.d.ts

@@ -0,0 +1,34 @@
+import type { GitRepository } from '@hachej/boring-files/git';
+import { Type } from '@earendil-works/pi-ai';
+/**
+ * The host passes the same authorized working repository used by other callers, or nothing: then each call uses the repository of
+ * its own workspace, the binding attached to the env Pi handed the call (`withWorkspace` in `@hachej/boring-agent/workspaces`), so one
+ * harness serves a repository per person. Git mutations have no replay receipts.
+ */
+export declare function createGitTool(repository?: GitRepository): import("@earendil-works/pi-durable").ToolRegistration<Type.TUnion<[Type.TObject<{
+    operation: Type.TUnion<[Type.TLiteral<"init">, Type.TLiteral<"status">, Type.TLiteral<"log">, Type.TLiteral<"branches">]>;
+}>, Type.TObject<{
+    operation: Type.TUnion<[Type.TLiteral<"add">, Type.TLiteral<"remove">]>;
+    path: Type.TString;
+}>, Type.TObject<{
+    operation: Type.TLiteral<"commit">;
+    message: Type.TString;
+}>, Type.TObject<{
+    operation: Type.TUnion<[Type.TLiteral<"branch">, Type.TLiteral<"checkout">]>;
+    ref: Type.TString;
+}>, Type.TObject<{
+    operation: Type.TLiteral<"diff">;
+    before: Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"tree">;
+        ref: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"index">, Type.TLiteral<"worktree">]>;
+    }>]>;
+    after: Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"tree">;
+        ref: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TUnion<[Type.TLiteral<"index">, Type.TLiteral<"worktree">]>;
+    }>]>;
+}>]>, import("@earendil-works/chord").JsonValue>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.js

@@ -0,0 +1,79 @@
+import { defineTool } from '@earendil-works/pi-durable';
+import { Type } from '@earendil-works/pi-ai';
+import { workspaceFor } from './workspaces.js';
+/** Model-facing form of a diff side: decoded text, or a binary marker without the bytes. */
+function readable(version) {
+    if (!version)
+        return null;
+    const { oid, mode, bytes } = version;
+    try {
+        return { oid, mode, text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+    }
+    catch {
+        return { oid, mode, binary: true, size: bytes.length };
+    }
+}
+/**
+ * The host passes the same authorized working repository used by other callers, or nothing: then each call uses the repository of
+ * its own workspace, the binding attached to the env Pi handed the call (`withWorkspace` in `@hachej/boring-agent/workspaces`), so one
+ * harness serves a repository per person. Git mutations have no replay receipts.
+ */
+export function createGitTool(repository) {
+    const view = Type.Union([
+        Type.Object({ kind: Type.Literal('tree'), ref: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+        Type.Object({ kind: Type.Union([Type.Literal('index'), Type.Literal('worktree')]) }, { additionalProperties: false }),
+    ]);
+    return defineTool({
+        name: 'working_git',
+        description: 'Operate on the bound working repository. Removal affects only the index. Mutations may leave partial effects and are not publication.',
+        replay: 'unsafe',
+        parameters: Type.Union([
+            Type.Object({ operation: Type.Union([Type.Literal('init'), Type.Literal('status'), Type.Literal('log'), Type.Literal('branches')]) }, { additionalProperties: false }),
+            Type.Object({ operation: Type.Union([Type.Literal('add'), Type.Literal('remove')]), path: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+            Type.Object({ operation: Type.Literal('commit'), message: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+            Type.Object({ operation: Type.Union([Type.Literal('branch'), Type.Literal('checkout')]), ref: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+            Type.Object({ operation: Type.Literal('diff'), before: view, after: view }, { additionalProperties: false }),
+        ]),
+        execute: async (args, api, context) => {
+            const resolved = repository === undefined ? await workspaceFor(undefined, api, context) : undefined;
+            const selected = repository ?? (resolved && 'binding' in resolved ? resolved.binding.repository : undefined);
+            if (selected === undefined)
+                return { content: [{ type: 'text', text: 'This conversation has no working repository.' }], isError: true };
+            const signal = context.abortSignal;
+            let value;
+            switch (args.operation) {
+                case 'init':
+                    value = await selected.init(signal);
+                    break;
+                case 'status':
+                    value = await selected.status(signal);
+                    break;
+                case 'log':
+                    value = await selected.log(signal);
+                    break;
+                case 'branches':
+                    value = await selected.branches(signal);
+                    break;
+                case 'add':
+                    value = await selected.add(args.path, signal);
+                    break;
+                case 'remove':
+                    value = await selected.remove(args.path, signal);
+                    break;
+                case 'commit':
+                    value = await selected.commit(args.message, signal);
+                    break;
+                case 'branch':
+                    value = await selected.branch(args.ref, signal);
+                    break;
+                case 'checkout':
+                    value = await selected.checkout(args.ref, signal);
+                    break;
+                case 'diff':
+                    value = (await selected.diff(args.before, args.after, signal)).map(change => ({ path: change.path, before: readable(change.before), after: readable(change.after) }));
+                    break;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify({ operation: args.operation, value: value ?? null }) }] };
+        },
+    });
+}

package/dist/harness-pool.d.ts

@@ -0,0 +1,38 @@
+import type { Harness } from '@earendil-works/pi-durable';
+import type { Context } from '@earendil-works/chord';
+/** What `create` returns: the owner's harness, anything else the host keeps with it, and how to close it (default `harness.close`). */
+export interface PooledHarness {
+    readonly harness: Harness;
+    readonly close?: () => Promise<void>;
+}
+export interface HarnessPoolOptions<T extends PooledHarness = PooledHarness> {
+    /** Open the harness of `owner`. Called once per owner while it stays open; must not share storage with another owner. */
+    readonly create: (owner: string) => Promise<T>;
+    /** Long-lived context for `inspect` and `close`. */
+    readonly context: Context;
+    /** Close an owner's harness this long after its last use (default 10 minutes; `Infinity`: never). */
+    readonly idleMs?: number;
+    /** A close that failed. Must not throw. */
+    readonly onError?: (error: unknown, owner: string) => void;
+}
+export interface HarnessLease<T extends PooledHarness = PooledHarness> {
+    readonly owned: T;
+    /** Return the hold. It never closes the harness; the pool does that once idle. Idempotent. */
+    readonly release: () => void;
+}
+export interface HarnessPool<T extends PooledHarness = PooledHarness> {
+    /** Hold the harness of `owner`, opening it when needed. */
+    readonly acquire: (owner: string) => Promise<HarnessLease<T>>;
+    /** Run `operation` on the owner's harness, held for its duration. */
+    readonly use: <R>(owner: string, operation: (owned: T) => Promise<R>) => Promise<R>;
+    /** A transport operation: the harness stays held until the response body ends or is cancelled (a watch stream). */
+    readonly respond: (owner: string, operation: (owned: T) => Promise<Response>) => Promise<Response>;
+    /** The owners whose harness is open now. */
+    readonly owners: () => string[];
+    /** What `create` returned for every harness open now, without holding any (a health check reads them). */
+    readonly opened: () => Promise<T[]>;
+    /** Close every harness (host shutdown). */
+    readonly close: () => Promise<void>;
+}
+export declare function createHarnessPool<T extends PooledHarness = PooledHarness>(options: HarnessPoolOptions<T>): HarnessPool<T>;
+//# sourceMappingURL=harness-pool.d.ts.map

package/dist/harness-pool.js

@@ -0,0 +1,134 @@
+export function createHarnessPool(options) {
+    const { context } = options;
+    const idleMs = options.idleMs ?? 10 * 60_000;
+    if (!(idleMs > 0))
+        throw new TypeError('idleMs must be positive');
+    const entries = new Map();
+    let closed = false;
+    function arm(owner, entry) {
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
+        if (!Number.isFinite(idleMs))
+            return;
+        entry.timer = setTimeout(() => { void sweep(owner, entry); }, Math.max(0, entry.lastUsed + idleMs - Date.now()));
+        entry.timer.unref?.();
+    }
+    async function sweep(owner, entry) {
+        entry.timer = undefined;
+        if (entries.get(owner) !== entry || entry.leases > 0)
+            return;
+        if (Date.now() - entry.lastUsed < idleMs)
+            return arm(owner, entry);
+        // Background work (a subagent, a queued follow-up) keeps the harness open: closing it would stop a task nobody is watching.
+        let busy = true;
+        try {
+            const inspection = await (await entry.opening).harness.inspect(context);
+            busy = inspection.tasks.length > 0 || inspection.submissions.length > 0;
+        }
+        catch { /* keep it */ }
+        if (entries.get(owner) !== entry || entry.leases > 0)
+            return;
+        if (busy) {
+            entry.lastUsed = Date.now();
+            return arm(owner, entry);
+        }
+        await dispose(owner, entry);
+    }
+    function dispose(owner, entry) {
+        if (entries.get(owner) === entry)
+            entries.delete(owner);
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
+        entry.closing ??= entry.opening.then(owned => owned.close ? owned.close() : owned.harness.close(context), () => undefined).catch(error => { options.onError?.(error, owner); });
+        return entry.closing;
+    }
+    async function acquire(owner) {
+        if (closed)
+            throw new Error('The harness pool is closed');
+        if (typeof owner !== 'string' || owner === '')
+            throw new TypeError('An owner key is required');
+        let entry = entries.get(owner);
+        if (entry === undefined) {
+            const opening = Promise.resolve().then(() => options.create(owner));
+            const created = { opening, leases: 0, lastUsed: Date.now() };
+            entries.set(owner, created);
+            opening.catch(() => { if (entries.get(owner) === created)
+                entries.delete(owner); });
+            entry = created;
+        }
+        const held = entry;
+        held.leases++;
+        held.lastUsed = Date.now();
+        let owned;
+        try {
+            owned = await held.opening;
+        }
+        catch (error) {
+            held.leases--;
+            throw error;
+        }
+        let released = false;
+        return { owned, release: () => {
+                if (released)
+                    return;
+                released = true;
+                held.leases--;
+                held.lastUsed = Date.now();
+                if (held.leases === 0 && entries.get(owner) === held)
+                    arm(owner, held);
+            } };
+    }
+    return {
+        acquire,
+        use: async (owner, operation) => {
+            const lease = await acquire(owner);
+            try {
+                return await operation(lease.owned);
+            }
+            finally {
+                lease.release();
+            }
+        },
+        respond: async (owner, operation) => {
+            const lease = await acquire(owner);
+            let response;
+            try {
+                response = await operation(lease.owned);
+            }
+            catch (error) {
+                lease.release();
+                throw error;
+            }
+            if (response.body === null) {
+                lease.release();
+                return response;
+            }
+            const reader = response.body.getReader();
+            const body = new ReadableStream({
+                async pull(controller) {
+                    try {
+                        const { done, value } = await reader.read();
+                        if (done) {
+                            lease.release();
+                            controller.close();
+                        }
+                        else
+                            controller.enqueue(value);
+                    }
+                    catch (error) {
+                        lease.release();
+                        controller.error(error);
+                    }
+                },
+                async cancel(reason) { lease.release(); await reader.cancel(reason); },
+            });
+            return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+        },
+        owners: () => [...entries.keys()],
+        opened: async () => (await Promise.all([...entries.values()].map(entry => entry.opening.catch(() => undefined)))).filter((owned) => owned !== undefined),
+        close: async () => {
+            closed = true;
+            await Promise.all([...entries].map(([owner, entry]) => dispose(owner, entry)));
+        },
+    };
+}