attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/session/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Session domain types.
+ *
+ * A session is the authority boundary for one agent's workspace work: it binds
+ * an agent identity to a set of real, host-approved roots, a permission set,
+ * a TTL and a private JSON context. Nothing in this module is model-authored:
+ * the host opens sessions and hands the resulting credential to the transport,
+ * which binds every tool call to exactly one session.
+ *
+ * Sessions are deliberately separate from `runtime/session.ts`. That session is
+ * the cognitive memory of a turn loop; this one is a data-isolation and identity
+ * record. Sharing a word is cheaper than pretending the two lifecycles match.
+ */
+/**
+ * Opaque session key. Kept as a branded string so a path, an agent id or a
+ * random token can never be passed where a session id is expected.
+ */
+export type SessionId = string;
+/**
+ * Stable host-assigned agent identity. It is not a model name and not a token.
+ */
+export type AgentId = string;
+/**
+ * Closed session lifecycle. `expired` and `revoked` are terminal for reads;
+ * a host may audit them, but no adapter may silently revive one.
+ */
+export type SessionStatus = "active" | "suspended" | "revoked" | "expired";
+/**
+ * Operations a session can be granted. `execute` is intentionally absent:
+ * this layer reads and writes files, it does not spawn processes.
+ */
+export type SessionOperation = "read" | "write" | "create" | "remove" | "list";
+/**
+ * JSON value accepted by the session context store. The store rejects values
+ * that cannot round-trip through canonical JSON (functions, symbols, bigint,
+ * cyclic objects) instead of silently coercing them.
+ */
+export type SessionJson = null | boolean | number | string | SessionJson[] | {
+    [key: string]: SessionJson;
+};
+/**
+ * Coarse permission set plus per-session quotas. The limits are repeated here
+ * rather than read from a global configuration so two sessions in one process
+ * cannot widen each other's budget.
+ */
+export interface SessionPermissions {
+    readonly read: boolean;
+    readonly write: boolean;
+    readonly create: boolean;
+    readonly remove: boolean;
+    readonly maxReadBytes: number;
+    readonly maxWriteBytes: number;
+    readonly maxTreeNodes: number;
+    readonly maxContextEntries: number;
+    readonly maxContextBytes: number;
+}
+/**
+ * One host-approved directory. `path` must be absolute and is resolved through
+ * `realpath` when the session is opened; `id` is the stable key tools use so a
+ * response never has to echo a host path the model should not depend on.
+ */
+export interface SessionRoot {
+    readonly id: string;
+    readonly path: string;
+    readonly writable: boolean;
+    readonly exclude: readonly string[];
+}
+/**
+ * Public session record. It never contains the bearer secret; authentication
+ * state lives only as a hash inside the registry and the persistence adapter.
+ */
+export interface SessionDescriptor {
+    readonly id: SessionId;
+    readonly agentId: AgentId;
+    readonly label: string;
+    readonly status: SessionStatus;
+    readonly roots: readonly SessionRoot[];
+    readonly permissions: SessionPermissions;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly idleExpiresAt: string;
+    readonly revision: number;
+    readonly parentId?: SessionId;
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Host input for opening a session. Every field except the agent identity is
+ * optional and defaults are deliberately conservative.
+ */
+export interface SessionOpenInput {
+    readonly agentId: AgentId;
+    readonly label?: string;
+    readonly roots: readonly SessionRoot[];
+    readonly permissions?: Partial<SessionPermissions>;
+    readonly ttlMs?: number;
+    readonly idleTtlMs?: number;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly parentId?: SessionId;
+}
+/**
+ * One-time credential returned by `open`/`fork`/`rotate`. The raw token is
+ * shown exactly once; only its hash is persisted.
+ */
+export interface SessionCredential {
+    readonly sessionId: SessionId;
+    readonly token: string;
+}
+/**
+ * Result of a successful authentication. Callers keep the descriptor and never
+ * the token hash; the hash is exposed for audit adapters only.
+ */
+export interface SessionAuthentication {
+    readonly descriptor: SessionDescriptor;
+    readonly tokenHash: string;
+}
+/**
+ * One namespaced context entry. `bytes` is the canonical UTF-8 size used for
+ * quota accounting, not `String.length`.
+ */
+export interface SessionContextEntry {
+    readonly namespace: string;
+    readonly key: string;
+    readonly value: SessionJson;
+    readonly bytes: number;
+    readonly updatedAt: string;
+}
+/**
+ * Immutable view of a session's context. `bytes` is the sum of entry sizes.
+ */
+export interface SessionContextSnapshot {
+    readonly sessionId: SessionId;
+    readonly entries: readonly SessionContextEntry[];
+    readonly bytes: number;
+}
+/**
+ * Fork input. A fork gets a fresh id, secret and revision; it shares no mutable
+ * object with its parent, so a write in one cannot be observed by the other.
+ */
+export interface SessionForkInput {
+    readonly label?: string;
+    readonly ttlMs?: number;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/**
+ * Persistence port for descriptors. Adapters may be in-memory, JSON or SQLite;
+ * the registry never knows which. Context persistence is a separate port
+ * because some hosts persist session identity but never persist workspace data.
+ */
+export interface SessionStore {
+    load(sessionId: SessionId): SessionDescriptor | undefined;
+    /**
+     * Token hash needed to restore authentication after a restart. A store that
+     * chooses not to persist secrets returns `undefined`, which makes restored
+     * sessions host-only until the host rotates the token.
+     */
+    loadSecret(sessionId: SessionId): string | undefined;
+    save(descriptor: SessionDescriptor, tokenHash: string): void;
+    delete(sessionId: SessionId): boolean;
+    list(agentId?: AgentId): SessionDescriptor[];
+}
+/**
+ * Persistence port for context entries. `replace` is atomic per session so a
+ * crash cannot leave half a context visible to the next process.
+ */
+export interface SessionContextStore {
+    load(sessionId: SessionId): SessionContextEntry[];
+    put(sessionId: SessionId, entry: SessionContextEntry): void;
+    delete(sessionId: SessionId, namespace: string, key: string): boolean;
+    deleteSession(sessionId: SessionId): void;
+    replace(sessionId: SessionId, entries: readonly SessionContextEntry[]): void;
+}
+/**
+ * Clock injection point. Tests use it to exercise TTL/expiry paths without
+ * sleeping; production uses `Date.now`.
+ */
+export interface SessionClock {
+    now(): Date;
+}
+/**
+ * Registry limits. A host cannot raise them after construction, which keeps a
+ * compromised caller from turning many small sessions into unbounded memory.
+ */
+export interface SessionRegistryLimits {
+    readonly maxSessions: number;
+    readonly maxRootsPerSession: number;
+    readonly maxContextEntries: number;
+    readonly maxContextBytes: number;
+    readonly maxTokenRotations: number;
+}
+/**
+ * Normalized defaults for opening a session when the host omits a field.
+ */
+export interface SessionDefaults {
+    readonly ttlMs: number;
+    readonly idleTtlMs: number;
+    readonly label: string;
+}
+/**
+ * Options for the registry. `store` and `contextStore` are optional so the
+ * module is useful in memory-only tests; a SQLite host supplies both adapters.
+ */
+export interface SessionRegistryOptions {
+    readonly limits?: Partial<SessionRegistryLimits>;
+    readonly defaults?: Partial<SessionDefaults>;
+    readonly store?: SessionStore;
+    readonly contextStore?: SessionContextStore;
+    readonly clock?: SessionClock;
+}
+/**
+ * Error codes are part of the adapter contract: a transport can map a failure
+ * to a stable code without parsing English prose.
+ */
+export type SessionErrorCode = "invalid_arguments" | "invalid_identity" | "session_not_found" | "session_expired" | "session_revoked" | "session_suspended" | "session_forbidden" | "session_capacity" | "context_quota" | "context_conflict" | "store_failure";
+/**
+ * Host-side session summary used by diagnostics and the `session` tool.
+ */
+export interface SessionSummary {
+    readonly id: SessionId;
+    readonly agentId: AgentId;
+    readonly label: string;
+    readonly status: SessionStatus;
+    readonly roots: readonly Pick<SessionRoot, "id" | "writable">[];
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly remainingMs: number;
+    readonly revision: number;
+}

package/lib/session/types.js

@@ -0,0 +1,14 @@
+/**
+ * Session domain types.
+ *
+ * A session is the authority boundary for one agent's workspace work: it binds
+ * an agent identity to a set of real, host-approved roots, a permission set,
+ * a TTL and a private JSON context. Nothing in this module is model-authored:
+ * the host opens sessions and hands the resulting credential to the transport,
+ * which binds every tool call to exactly one session.
+ *
+ * Sessions are deliberately separate from `runtime/session.ts`. That session is
+ * the cognitive memory of a turn loop; this one is a data-isolation and identity
+ * record. Sharing a word is cheaper than pretending the two lifecycles match.
+ */
+export {};

package/lib/structure/index.d.ts

@@ -17,4 +17,5 @@ export * from "./queue.js";
 export * from "./redBlackTree.js";
 export * from "./segmentTree.js";
 export * from "./stack.js";
+export * from "./trie.js";
 export * from "./unordered.js";

package/lib/structure/index.js

@@ -17,4 +17,5 @@ export * from "./queue.js";
 export * from "./redBlackTree.js";
 export * from "./segmentTree.js";
 export * from "./stack.js";
+export * from "./trie.js";
 export * from "./unordered.js";

package/lib/structure/trie.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Character trie (prefix tree).
+ *
+ * Used where a hash map cannot answer "which keys start with this prefix?":
+ * outline symbol lookup, root-relative path prefixes and import specifier
+ * completion. Keys are JavaScript strings; children use a `Map` rather than a
+ * fixed alphabet so Unicode identifiers work without a 65k-entry node.
+ *
+ * The trie is a mutable index, not a source of truth. `insert` replaces the
+ * value at an existing terminal; `delete` removes the terminal and prunes the
+ * now-empty path. Traversal is iterative so a pathological key length cannot
+ * exhaust the call stack.
+ */
+/**
+ * One trie node. `terminal` is tracked separately from `value` because a key
+ * may legitimately store `undefined`; `has` must still distinguish "present
+ * with no value" from "absent".
+ */
+export interface TrieNode<T> {
+    readonly children: Map<string, TrieNode<T>>;
+    terminal: boolean;
+    value?: T;
+}
+/**
+ * A prefix tree over string keys.
+ *
+ * @typeParam T - Value stored at a terminal key.
+ */
+export declare class Trie<T> {
+    private readonly root;
+    private count;
+    /**
+     * Number of terminal keys.
+     */
+    get size(): number;
+    /**
+     * Insert or replace one key.
+     *
+     * @param key - Non-empty key.
+     * @param value - Value stored at the terminal.
+     */
+    insert(key: string, value: T): void;
+    /**
+     * Read a key's value. The second element distinguishes "absent" from
+     * "present with an `undefined` value".
+     *
+     * @param key - Key to locate.
+     * @returns Found state and value.
+     */
+    find(key: string): {
+        found: boolean;
+        value?: T;
+    };
+    /**
+     * Value at a terminal key, or `undefined`.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Whether a key is present.
+     */
+    has(key: string): boolean;
+    /**
+     * Remove one key. Returns `false` when the key was absent.
+     */
+    delete(key: string): boolean;
+    /**
+     * All terminal keys under a prefix, in insertion-independent lexical order.
+     *
+     * @param prefix - Optional prefix; empty returns every key.
+     */
+    keys(prefix?: string): string[];
+    /**
+     * All terminal entries under a prefix.
+     */
+    entries(prefix?: string): Array<readonly [string, T]>;
+    /**
+     * Longest terminal prefix of `text`, useful for matching a selector or a
+     * path against a known set without generating every prefix.
+     */
+    longestPrefix(text: string): {
+        key: string;
+        value: T;
+    } | undefined;
+    /**
+     * Remove every key.
+     */
+    clear(): void;
+}

package/lib/structure/trie.js

@@ -0,0 +1,183 @@
+/**
+ * Character trie (prefix tree).
+ *
+ * Used where a hash map cannot answer "which keys start with this prefix?":
+ * outline symbol lookup, root-relative path prefixes and import specifier
+ * completion. Keys are JavaScript strings; children use a `Map` rather than a
+ * fixed alphabet so Unicode identifiers work without a 65k-entry node.
+ *
+ * The trie is a mutable index, not a source of truth. `insert` replaces the
+ * value at an existing terminal; `delete` removes the terminal and prunes the
+ * now-empty path. Traversal is iterative so a pathological key length cannot
+ * exhaust the call stack.
+ */
+const createNode = () => ({ children: new Map(), terminal: false });
+/**
+ * A prefix tree over string keys.
+ *
+ * @typeParam T - Value stored at a terminal key.
+ */
+export class Trie {
+    root = createNode();
+    count = 0;
+    /**
+     * Number of terminal keys.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * Insert or replace one key.
+     *
+     * @param key - Non-empty key.
+     * @param value - Value stored at the terminal.
+     */
+    insert(key, value) {
+        if (key.length === 0) {
+            throw new RangeError("trie key must not be empty");
+        }
+        let node = this.root;
+        for (let index = 0; index < key.length; index += 1) {
+            const character = key[index];
+            let child = node.children.get(character);
+            if (child === (void 0)) {
+                child = createNode();
+                node.children.set(character, child);
+            }
+            node = child;
+        }
+        if (!node.terminal) {
+            this.count += 1;
+        }
+        node.terminal = true;
+        node.value = value;
+    }
+    /**
+     * Read a key's value. The second element distinguishes "absent" from
+     * "present with an `undefined` value".
+     *
+     * @param key - Key to locate.
+     * @returns Found state and value.
+     */
+    find(key) {
+        let node = this.root;
+        for (let index = 0; index < key.length; index += 1) {
+            node = node.children.get(key[index]);
+            if (node === (void 0)) {
+                return { found: false };
+            }
+        }
+        return node.terminal ? { found: true, value: node.value } : { found: false };
+    }
+    /**
+     * Value at a terminal key, or `undefined`.
+     */
+    get(key) {
+        return this.find(key).value;
+    }
+    /**
+     * Whether a key is present.
+     */
+    has(key) {
+        return this.find(key).found;
+    }
+    /**
+     * Remove one key. Returns `false` when the key was absent.
+     */
+    delete(key) {
+        if (key.length === 0) {
+            return false;
+        }
+        const path = [];
+        let node = this.root;
+        for (let index = 0; index < key.length; index += 1) {
+            const character = key[index];
+            const child = node.children.get(character);
+            if (child === (void 0)) {
+                return false;
+            }
+            path.push({ character, node });
+            node = child;
+        }
+        if (!node.terminal) {
+            return false;
+        }
+        node.terminal = false;
+        delete node.value;
+        this.count -= 1;
+        for (let index = path.length - 1; index >= 0; index -= 1) {
+            const edge = path[index];
+            const child = edge.node.children.get(edge.character);
+            if (child === (void 0) || child.terminal || child.children.size > 0) {
+                break;
+            }
+            edge.node.children.delete(edge.character);
+        }
+        return true;
+    }
+    /**
+     * All terminal keys under a prefix, in insertion-independent lexical order.
+     *
+     * @param prefix - Optional prefix; empty returns every key.
+     */
+    keys(prefix = "") {
+        return this.entries(prefix).map((entry) => entry[0]);
+    }
+    /**
+     * All terminal entries under a prefix.
+     */
+    entries(prefix = "") {
+        let start = this.root;
+        for (let index = 0; index < prefix.length; index += 1) {
+            start = start.children.get(prefix[index]);
+            if (start === (void 0)) {
+                return [];
+            }
+        }
+        const result = [];
+        const stack = [{ key: prefix, node: start }];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (current.node.terminal) {
+                result.push([current.key, current.node.value]);
+            }
+            const characters = [...current.node.children.keys()].reverse();
+            for (let index = 0; index < characters.length; index += 1) {
+                const character = characters[index];
+                const child = current.node.children.get(character);
+                if (child !== (void 0)) {
+                    stack.push({ key: current.key + character, node: child });
+                }
+            }
+        }
+        result.sort((left, right) => (left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0));
+        return result;
+    }
+    /**
+     * Longest terminal prefix of `text`, useful for matching a selector or a
+     * path against a known set without generating every prefix.
+     */
+    longestPrefix(text) {
+        let node = this.root;
+        let match = (void 0);
+        for (let index = 0; index < text.length; index += 1) {
+            node = node.children.get(text[index]);
+            if (node === (void 0)) {
+                break;
+            }
+            if (node.terminal) {
+                match = { key: text.slice(0, index + 1), value: node.value };
+            }
+        }
+        return match;
+    }
+    /**
+     * Remove every key.
+     */
+    clear() {
+        this.root.children.clear();
+        this.root.terminal = false;
+        delete this.root.value;
+        this.count = 0;
+    }
+}

package/lib/syntax/byteIndex.d.ts

@@ -0,0 +1,44 @@
+import type { SourceRange as OutlineRange } from "./types.js";
+export declare class ByteLineIndex {
+    private readonly tree;
+    private readonly starts;
+    private readonly text;
+    private readonly total;
+    /**
+     * Bytes before the decoded text (a UTF-8/UTF-16 BOM). Symbol ranges are
+     * offsets in the original file, while the decoded text starts after the
+     * marker; adding the base here keeps both coordinate systems consistent.
+     */
+    private readonly base;
+    constructor(text: string, bomBytes?: number);
+    /**
+     * Number of logical lines. The empty file has zero lines.
+     */
+    get lineCount(): number;
+    /**
+     * Start byte offset of a 1-based line. Lines past EOF clamp to the end.
+     */
+    startByte(line: number): bigint;
+    /**
+     * Half-open end byte offset for an inclusive line.
+     */
+    endByte(line: number): bigint;
+    /**
+     * Byte length of the whole text.
+     */
+    byteLength(): bigint;
+    /**
+     * Build a half-open byte / inclusive line range. Inputs are clamped so a
+     * parser can be approximate without producing an invalid range.
+     */
+    range(startLine: number, endLine: number): OutlineRange;
+    /**
+     * Range covering the entire text; used for a file anchor.
+     */
+    fullRange(): OutlineRange;
+    /**
+     * Source slice for a range, useful for a `detail`/signature preview.
+     */
+    slice(range: OutlineRange): string;
+    private offsetOf;
+}