@jigging/agent-acp 0.0.0 → 0.1.0-alpha.3

package/dist/transport.d.ts

@@ -0,0 +1,56 @@
+/** Framing is data transport, not permission to dispatch an ACP operation. */
+export declare const FINITE_ACP_LIMITS: Readonly<{
+    fragmentBytes: 8192;
+    frameBytes: 16777216;
+    requestBytes: 8388608;
+    responseBytes: 33554432;
+    requestFrames: 64;
+    responseFrames: 8192;
+    fragments: 16384;
+    identifierBytes: 1024;
+}>;
+export type FiniteAcpConfiguration = {
+    readonly configId: string;
+    readonly value: string;
+} | {
+    readonly configId: string;
+    readonly type: 'boolean';
+    readonly value: boolean;
+};
+export interface FiniteAcpReady {
+    readonly kind: 'ready';
+    readonly protocolVersion: 1;
+    readonly cwd: '/work';
+    readonly maxTurns: number;
+    readonly configuration: readonly FiniteAcpConfiguration[];
+    readonly modeId?: string;
+    readonly restoreSessionId?: string;
+}
+export interface FiniteAcpFragment {
+    readonly kind: 'data';
+    readonly text: string;
+    readonly end: boolean;
+}
+export declare class FiniteAcpTransportError extends Error {
+    constructor(message: string);
+}
+/** Snapshot the host's non-secret ready record; this copy grants no authority. */
+export declare function readFiniteAcpReady(value: unknown): FiniteAcpReady;
+/** One complete JSON frame, split only between Unicode scalars. No replay IDs. */
+export declare function fragmentFiniteAcpFrame(text: string): Generator<FiniteAcpFragment>;
+/** Bounded single-frame assembly. Failure permanently invalidates this stream. */
+export declare class FiniteAcpFrames {
+    private readonly maximumBytes;
+    private readonly maximumFrames;
+    private totalBytes;
+    private frameBytes;
+    private frames;
+    private fragments;
+    private parts;
+    private ended;
+    private failed;
+    constructor(direction: 'requests' | 'responses');
+    accept(value: unknown): string | undefined;
+    finish(): void;
+    private guard;
+}

package/dist/transport.js

@@ -0,0 +1,209 @@
+/** Framing is data transport, not permission to dispatch an ACP operation. */
+export const FINITE_ACP_LIMITS = Object.freeze({
+    fragmentBytes: 8_192,
+    frameBytes: 16_777_216,
+    requestBytes: 8_388_608,
+    responseBytes: 33_554_432,
+    requestFrames: 64,
+    responseFrames: 8_192,
+    fragments: 16_384,
+    identifierBytes: 1_024,
+});
+export class FiniteAcpTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FiniteAcpTransportError';
+    }
+}
+const encoder = new TextEncoder();
+/** Does not invoke getters or accept non-data objects at a library boundary. */
+function object(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        invalid('Expected an object');
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype)
+        invalid('Expected a data object');
+    const result = Object.create(null);
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string')
+            invalid('Unexpected object key');
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value'))
+            invalid('Expected data properties');
+        result[key] = descriptor.value;
+    }
+    return result;
+}
+function exact(value, required, optional = []) {
+    if (required.some((key) => !Object.hasOwn(value, key)) ||
+        Object.keys(value).some((key) => !required.includes(key) && !optional.includes(key)))
+        invalid('Unexpected object fields');
+}
+/** Count scalar UTF-8 bytes without replacing invalid Unicode or allocating it. */
+function textBytes(value, maximum, empty = false) {
+    if (typeof value !== 'string' || (!empty && value.length === 0))
+        invalid('Expected nonempty text');
+    let bytes = 0;
+    for (let index = 0; index < value.length; index++) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                invalid('Text is not Unicode scalar data');
+            bytes += 4;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            invalid('Text is not Unicode scalar data');
+        else
+            bytes += unit < 0x80 ? 1 : unit < 0x800 ? 2 : 3;
+        if (bytes > maximum)
+            invalid('Text exceeds the finite ACP byte limit');
+    }
+    return bytes;
+}
+function identifier(value) {
+    textBytes(value, FINITE_ACP_LIMITS.identifierBytes);
+    if (value.includes('\0'))
+        invalid('Identifier contains NUL');
+    return value;
+}
+/** Snapshot the host's non-secret ready record; this copy grants no authority. */
+export function readFiniteAcpReady(value) {
+    const record = object(value);
+    exact(record, ['kind', 'protocolVersion', 'cwd', 'maxTurns', 'configuration'], ['modeId', 'restoreSessionId']);
+    if (record.kind !== 'ready' ||
+        record.protocolVersion !== 1 ||
+        record.cwd !== '/work' ||
+        typeof record.maxTurns !== 'number' ||
+        !Number.isSafeInteger(record.maxTurns) ||
+        record.maxTurns < 1 ||
+        record.maxTurns > 8 ||
+        !Array.isArray(record.configuration) ||
+        record.configuration.length > 16)
+        invalid('Invalid finite ACP ready record');
+    const names = new Set();
+    const input = record.configuration;
+    if (Object.getPrototypeOf(input) !== Array.prototype ||
+        Reflect.ownKeys(input).length !== input.length + 1)
+        invalid('Configuration must be a dense data array');
+    const configuration = Array.from({ length: input.length }, (_, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(input, String(index));
+        if (!descriptor || !Object.hasOwn(descriptor, 'value') || !descriptor.enumerable)
+            invalid('Configuration must be a dense data array');
+        const item = descriptor.value;
+        const entry = object(item);
+        exact(entry, ['configId', 'value'], ['type']);
+        const configId = identifier(entry.configId);
+        if (names.has(configId))
+            invalid('Duplicate finite ACP configuration');
+        names.add(configId);
+        if (entry.type === 'boolean') {
+            if (typeof entry.value !== 'boolean')
+                invalid('Invalid Boolean configuration');
+            return Object.freeze({ configId, type: 'boolean', value: entry.value });
+        }
+        if (Object.hasOwn(entry, 'type'))
+            invalid('Unsupported finite ACP configuration');
+        return Object.freeze({ configId, value: identifier(entry.value) });
+    });
+    const ready = Object.freeze({
+        kind: 'ready',
+        protocolVersion: 1,
+        cwd: '/work',
+        maxTurns: record.maxTurns,
+        configuration: Object.freeze(configuration),
+        ...(Object.hasOwn(record, 'modeId') ? { modeId: identifier(record.modeId) } : {}),
+        ...(Object.hasOwn(record, 'restoreSessionId')
+            ? { restoreSessionId: identifier(record.restoreSessionId) }
+            : {}),
+    });
+    if (encoder.encode(JSON.stringify(ready)).byteLength > 65_536)
+        invalid('Ready record exceeds the channel item bound');
+    return ready;
+}
+/** One complete JSON frame, split only between Unicode scalars. No replay IDs. */
+export function* fragmentFiniteAcpFrame(text) {
+    textBytes(text, FINITE_ACP_LIMITS.frameBytes);
+    let start = 0;
+    let bytes = 0;
+    for (let index = 0; index < text.length;) {
+        const code = text.codePointAt(index);
+        const width = code > 0xffff ? 2 : 1;
+        const size = code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+        if (bytes + size > FINITE_ACP_LIMITS.fragmentBytes) {
+            yield Object.freeze({ kind: 'data', text: text.slice(start, index), end: false });
+            start = index;
+            bytes = 0;
+        }
+        bytes += size;
+        index += width;
+    }
+    yield Object.freeze({ kind: 'data', text: text.slice(start), end: true });
+}
+/** Bounded single-frame assembly. Failure permanently invalidates this stream. */
+export class FiniteAcpFrames {
+    maximumBytes;
+    maximumFrames;
+    totalBytes = 0;
+    frameBytes = 0;
+    frames = 0;
+    fragments = 0;
+    parts = [];
+    ended = false;
+    failed = false;
+    constructor(direction) {
+        if (direction !== 'requests' && direction !== 'responses')
+            invalid('Unknown finite ACP direction');
+        this.maximumBytes =
+            direction === 'requests' ? FINITE_ACP_LIMITS.requestBytes : FINITE_ACP_LIMITS.responseBytes;
+        this.maximumFrames =
+            direction === 'requests' ? FINITE_ACP_LIMITS.requestFrames : FINITE_ACP_LIMITS.responseFrames;
+    }
+    accept(value) {
+        return this.guard(() => {
+            const record = object(value);
+            exact(record, ['kind', 'text', 'end']);
+            if (record.kind !== 'data' || typeof record.end !== 'boolean')
+                invalid('Invalid finite ACP fragment');
+            const bytes = textBytes(record.text, FINITE_ACP_LIMITS.fragmentBytes);
+            this.frameBytes += bytes;
+            this.totalBytes += bytes;
+            this.fragments++;
+            if (this.frameBytes > FINITE_ACP_LIMITS.frameBytes ||
+                this.totalBytes > this.maximumBytes ||
+                this.fragments > FINITE_ACP_LIMITS.fragments)
+                invalid('Finite ACP stream exceeds its bounds');
+            this.parts.push(record.text);
+            if (!record.end)
+                return undefined;
+            if (++this.frames > this.maximumFrames)
+                invalid('Finite ACP stream has too many frames');
+            const frame = this.parts.join('');
+            this.parts = [];
+            this.frameBytes = 0;
+            return frame;
+        });
+    }
+    finish() {
+        this.guard(() => {
+            if (this.parts.length !== 0)
+                invalid('Finite ACP stream ended inside a frame');
+            this.ended = true;
+        });
+    }
+    guard(action) {
+        if (this.failed || this.ended)
+            invalid('Finite ACP stream is not open');
+        try {
+            return action();
+        }
+        catch (error) {
+            this.failed = true;
+            this.parts = [];
+            throw error;
+        }
+    }
+}
+function invalid(message) {
+    throw new FiniteAcpTransportError(message);
+}

package/dist/updates.d.ts

@@ -0,0 +1,16 @@
+import type { ChannelSender, JsonValue } from '@jigging/flow';
+/** Optional presentation never backpressures the essential ACP conversation. */
+export declare class OptionalUpdates {
+    private readonly sender;
+    private readonly signal;
+    private readonly stopped;
+    private readonly queue;
+    private bytes;
+    private pumping;
+    private incomplete;
+    constructor(sender: ChannelSender | undefined, signal: AbortSignal);
+    offer(value: JsonValue): void;
+    finish(): Promise<void>;
+    private pump;
+    private stop;
+}

package/dist/updates.js

@@ -0,0 +1,77 @@
+const encoder = new TextEncoder();
+const MAX_ITEMS = 16;
+const MAX_BYTES = 262_144;
+const SEND_WAIT_MS = 500;
+/** Optional presentation never backpressures the essential ACP conversation. */
+export class OptionalUpdates {
+    sender;
+    signal;
+    stopped = new AbortController();
+    queue = [];
+    bytes = 0;
+    pumping;
+    incomplete = false;
+    constructor(sender, signal) {
+        this.sender = sender;
+        this.signal = signal;
+    }
+    offer(value) {
+        if (!this.sender || this.incomplete || this.signal.aborted)
+            return;
+        const bytes = encoder.encode(JSON.stringify(value)).byteLength;
+        if (bytes > 65_536 || this.queue.length >= MAX_ITEMS || this.bytes + bytes > MAX_BYTES) {
+            this.stop();
+            return;
+        }
+        this.queue.push({ value, bytes });
+        this.bytes += bytes;
+        this.pumping ??= this.pump();
+    }
+    async finish() {
+        await this.pumping;
+        if (!this.sender)
+            return;
+        try {
+            await this.sender.close(this.incomplete ? { error: 'LAGGED' } : undefined);
+        }
+        catch {
+            this.stop();
+        }
+    }
+    async pump() {
+        try {
+            while (this.queue.length && !this.incomplete) {
+                const item = this.queue[0];
+                const timer = new AbortController();
+                const timeout = setTimeout(() => timer.abort(), SEND_WAIT_MS);
+                try {
+                    await this.sender.send(item.value, {
+                        signal: AbortSignal.any([this.signal, this.stopped.signal, timer.signal]),
+                    });
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+                if (!this.incomplete) {
+                    this.queue.shift();
+                    this.bytes -= item.bytes;
+                }
+            }
+        }
+        catch {
+            this.stop();
+        }
+        finally {
+            this.pumping = undefined;
+        }
+    }
+    stop() {
+        if (this.incomplete)
+            return;
+        this.incomplete = true;
+        this.queue.length = 0;
+        this.bytes = 0;
+        this.stopped.abort();
+        console.error('Agent progress is incomplete; the execution result remains separate.');
+    }
+}

package/justfile

@@ -0,0 +1,32 @@
+# ---------------------------------------------------------------------------- #
+#                                   COMMANDS                                   #
+# ---------------------------------------------------------------------------- #
+
+@default:
+    just --list
+
+# Compile the public transport and bundle the complete ordinary Flow runtime
+@build: clean
+    bun node_modules/typescript/bin/tsc -p tsconfig.json
+    bun build src/flow.ts --target=node --format=esm --outfile=dist/flow.js
+
+# Remove only this package's generated output before compiling
+clean:
+    #!/usr/bin/env bun
+    import { rm } from 'node:fs/promises';
+    await rm('dist', { recursive: true, force: true });
+
+# Build, then pack source and runtime with ordinary dependency declarations
+[positional-arguments]
+@pack *args: build
+    bun pm pack --ignore-scripts "$@"
+
+# ---------------------------------------------------------------------------- #
+#                                    CHECKS                                    #
+# ---------------------------------------------------------------------------- #
+
+[positional-arguments]
+@test *args:
+    bun test "$@"
+
+check: build test