attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/session/context.js

@@ -0,0 +1,419 @@
+/**
+ * Per-session JSON context with canonical byte accounting.
+ *
+ * The context is the only mutable data a session owns that is not a file. It is
+ * partitioned by session id so two sessions in one process can never observe
+ * each other's entries. Values are canonicalised before they are stored: that
+ * proves the value round-trips through strict JSON, gives one definition of
+ * "bytes" for quotas, and rejects `bigint`, functions, `undefined`, cycles and
+ * unpaired surrogates instead of silently coercing them.
+ *
+ * Every returned entry is a `structuredClone`, so a caller that mutates a
+ * result cannot corrupt the store. Persistence is a separate port: a host that
+ * only wants identity persistence can omit it, and a host that supplies it gets
+ * synchronous `put`/`delete`/`replace` writes on the same calls that mutate
+ * memory. Loading is lazy (`ensure`) because a restored registry may hold many
+ * sessions the process never touches.
+ */
+import { Buffer } from "node:buffer";
+import { canonical } from "../semantic/canonical.js";
+import { fail } from "./errors.js";
+const DefaultMaxEntries = 256;
+const DefaultMaxBytes = 1024 * 1024;
+const MaxNameLength = 128;
+const ControlCharacters = /[\u0000-\u001f\u007f-\u009f]/;
+const SystemClock = { now: () => new Date() };
+const clone = (value) => structuredClone(value);
+/**
+ * A name must be well-formed Unicode. `JSON.stringify` tolerates a lone
+ * surrogate by escaping it, but a persistence adapter that binds UTF-8 cannot,
+ * so accepting one would make the stored key differ from the key the caller
+ * wrote.
+ */
+const isWellFormed = (value) => {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff) {
+                return false;
+            }
+            index += 1;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Session ids are opaque handles. They share the text rules but not the
+ * 128-code-unit namespace/key ceiling, because the ceiling is a context key
+ * contract rather than a session-id contract.
+ */
+const sessionIdIsValid = (value) => typeof (value) === "string" && value.length > 0 && value.trim().length > 0 && !ControlCharacters.test(value) && isWellFormed(value);
+const requireSessionId = (value) => (sessionIdIsValid(value) ? value : fail("invalid_arguments"));
+/**
+ * Namespace and key share one grammar: non-empty, at most 128 code units, no
+ * control characters and well-formed Unicode. The rule stays out of the error
+ * message; the code is the entire contract.
+ */
+const nameIsValid = (value) => sessionIdIsValid(value) && value.length <= MaxNameLength;
+const requireName = (value) => (nameIsValid(value) ? value : fail("invalid_arguments"));
+const requireLimit = (value, fallback) => {
+    if (value === (void 0)) {
+        return fallback;
+    }
+    if (!Number.isSafeInteger(value) || value < 1) {
+        return fail("invalid_arguments");
+    }
+    return value;
+};
+const entryIdentity = (namespace, key) => `${namespace}\u0000${key}`;
+export class SessionContexts {
+    persistence;
+    clock;
+    maxEntries;
+    maxBytes;
+    sessions = new Map();
+    sizes = new Map();
+    loaded = new Set();
+    constructor(options = {}) {
+        this.persistence = options.persistence;
+        this.clock = options.clock ?? SystemClock;
+        this.maxEntries = requireLimit(options.limits?.maxContextEntries, DefaultMaxEntries);
+        this.maxBytes = requireLimit(options.limits?.maxContextBytes, DefaultMaxBytes);
+    }
+    /**
+     * Load one session's persisted entries exactly once. An absent store, a
+     * store that has no row for the session and an empty result all mean "this
+     * session has no entries yet". A persisted partition that exceeds the
+     * current limits is rejected with `context_quota` rather than silently
+     * bypassing the quota; `clear` and `remove` still work without loading.
+     */
+    ensure(sessionId) {
+        const id = requireSessionId(sessionId);
+        if (this.loaded.has(id)) {
+            return;
+        }
+        const partition = new Map();
+        let total = 0;
+        const persistence = this.persistence;
+        if (persistence !== (void 0)) {
+            let loaded;
+            try {
+                loaded = persistence.load(id);
+            }
+            catch {
+                return fail("store_failure");
+            }
+            if (loaded === (void 0)) {
+                loaded = [];
+            }
+            if (!Array.isArray(loaded)) {
+                return fail("store_failure");
+            }
+            const stored = loaded;
+            const seen = new Set();
+            for (let index = 0; index < stored.length; index += 1) {
+                const storedEntry = stored[index];
+                if (!this.storedEntryIsValid(storedEntry)) {
+                    return fail("store_failure");
+                }
+                const entry = clone(storedEntry);
+                const identity = entryIdentity(entry.namespace, entry.key);
+                if (seen.has(identity)) {
+                    return fail("store_failure");
+                }
+                seen.add(identity);
+                let bucket = partition.get(entry.namespace);
+                if (bucket === (void 0)) {
+                    bucket = new Map();
+                    partition.set(entry.namespace, bucket);
+                }
+                bucket.set(entry.key, entry);
+                total += entry.bytes;
+            }
+            if (stored.length > this.maxEntries || total > this.maxBytes) {
+                return fail("context_quota");
+            }
+        }
+        this.sessions.set(id, partition);
+        this.sizes.set(id, total);
+        this.loaded.add(id);
+    }
+    /**
+     * Return one entry, or `undefined`. A missing session is an empty context,
+     * not an error: the registry owns session existence.
+     */
+    get(sessionId, namespace, key) {
+        const id = requireSessionId(sessionId);
+        const space = requireName(namespace);
+        const entryKey = requireName(key);
+        const bucket = this.partitionOf(id).get(space);
+        if (bucket === (void 0)) {
+            return (void 0);
+        }
+        const entry = bucket.get(entryKey);
+        return entry === (void 0) ? (void 0) : clone(entry);
+    }
+    /**
+     * Canonicalise, quota-check and store one value, returning the stored entry
+     * as a detached copy.
+     */
+    set(sessionId, namespace, key, value, at) {
+        const id = requireSessionId(sessionId);
+        const space = requireName(namespace);
+        const entryKey = requireName(key);
+        if (typeof (at) !== "string") {
+            return fail("invalid_arguments");
+        }
+        let updatedAt;
+        if (at.length === 0) {
+            updatedAt = this.clock.now().toISOString();
+        }
+        else {
+            updatedAt = at;
+        }
+        let text;
+        try {
+            text = canonical(value);
+        }
+        catch {
+            return fail("invalid_arguments");
+        }
+        const normalized = JSON.parse(text);
+        const bytes = Buffer.byteLength(text, "utf8");
+        const partition = this.partitionOf(id);
+        const bucket = partition.get(space);
+        const previous = bucket === (void 0) ? (void 0) : bucket.get(entryKey);
+        const total = (this.sizes.get(id) ?? 0) - (previous === (void 0) ? 0 : previous.bytes);
+        if (previous === (void 0) && this.countOf(id) + 1 > this.maxEntries) {
+            return fail("context_quota");
+        }
+        if (total + bytes > this.maxBytes) {
+            return fail("context_quota");
+        }
+        const entry = { namespace: space, key: entryKey, value: normalized, bytes, updatedAt };
+        this.persistPut(id, entry);
+        const target = bucket === (void 0) ? new Map() : bucket;
+        if (bucket === (void 0)) {
+            partition.set(space, target);
+        }
+        target.set(entryKey, entry);
+        this.sizes.set(id, total + bytes);
+        return clone(entry);
+    }
+    /**
+     * Remove one entry. Returns `false` when it never existed.
+     */
+    delete(sessionId, namespace, key) {
+        const id = requireSessionId(sessionId);
+        const space = requireName(namespace);
+        const entryKey = requireName(key);
+        const partition = this.partitionOf(id);
+        const bucket = partition.get(space);
+        if (bucket === (void 0)) {
+            return false;
+        }
+        const entry = bucket.get(entryKey);
+        if (entry === (void 0)) {
+            return false;
+        }
+        const persistence = this.persistence;
+        if (persistence !== (void 0)) {
+            try {
+                persistence.delete(id, space, entryKey);
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+        bucket.delete(entryKey);
+        if (bucket.size === 0) {
+            partition.delete(space);
+        }
+        this.sizes.set(id, Math.max(0, (this.sizes.get(id) ?? 0) - entry.bytes));
+        return true;
+    }
+    /**
+     * List entries for one session, optionally narrowed to one namespace.
+     * Ordering is deterministic (namespace, then key) so snapshots diff cleanly.
+     */
+    list(sessionId, namespace) {
+        const id = requireSessionId(sessionId);
+        const wanted = namespace === (void 0) ? (void 0) : requireName(namespace);
+        const partition = this.partitionOf(id);
+        const entries = [];
+        const namespaces = [...partition.keys()].sort();
+        for (let spaceIndex = 0; spaceIndex < namespaces.length; spaceIndex += 1) {
+            const space = namespaces[spaceIndex];
+            if (wanted !== (void 0) && space !== wanted) {
+                continue;
+            }
+            const bucket = partition.get(space);
+            if (bucket === (void 0)) {
+                continue;
+            }
+            const keys = [...bucket.keys()].sort();
+            for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
+                const entry = bucket.get(keys[keyIndex]);
+                if (entry !== (void 0)) {
+                    entries.push(clone(entry));
+                }
+            }
+        }
+        return entries;
+    }
+    /**
+     * Immutable view of one session's whole context.
+     */
+    snapshot(sessionId) {
+        const id = requireSessionId(sessionId);
+        const entries = this.list(id);
+        return { sessionId: id, entries, bytes: this.sizes.get(id) ?? 0 };
+    }
+    /**
+     * Canonical UTF-8 bytes charged against one session.
+     */
+    bytes(sessionId) {
+        const id = requireSessionId(sessionId);
+        this.ensure(id);
+        return this.sizes.get(id) ?? 0;
+    }
+    /**
+     * Drop every entry for one session. The empty state is persisted as a
+     * `replace`, which is atomic for an adapter that honours the port. This is
+     * deliberately an overwrite rather than a load-then-clear: a corrupt or
+     * over-quota persisted partition must still be removable by its host.
+     */
+    clear(sessionId) {
+        const id = requireSessionId(sessionId);
+        const persistence = this.persistence;
+        if (persistence !== (void 0)) {
+            try {
+                persistence.replace(id, []);
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+        this.sessions.set(id, new Map());
+        this.sizes.set(id, 0);
+        this.loaded.add(id);
+    }
+    /**
+     * Copy the source context into the target session. Values are deep copies,
+     * so the two sessions share no mutable object. The target's previous
+     * context, if any, is replaced.
+     */
+    fork(from, to) {
+        const source = requireSessionId(from);
+        const target = requireSessionId(to);
+        if (source === target) {
+            return fail("invalid_arguments");
+        }
+        const entries = this.list(source);
+        let total = 0;
+        for (let index = 0; index < entries.length; index += 1) {
+            total += entries[index].bytes;
+        }
+        if (entries.length > this.maxEntries || total > this.maxBytes) {
+            return fail("context_quota");
+        }
+        const persistence = this.persistence;
+        if (persistence !== (void 0)) {
+            try {
+                persistence.replace(target, entries.map((entry) => clone(entry)));
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+        const partition = new Map();
+        for (let index = 0; index < entries.length; index += 1) {
+            const entry = clone(entries[index]);
+            let bucket = partition.get(entry.namespace);
+            if (bucket === (void 0)) {
+                bucket = new Map();
+                partition.set(entry.namespace, bucket);
+            }
+            bucket.set(entry.key, entry);
+        }
+        this.sessions.set(target, partition);
+        this.sizes.set(target, total);
+        this.loaded.add(target);
+    }
+    /**
+     * Remove every entry for one session and its persisted partition.
+     */
+    remove(sessionId) {
+        const id = requireSessionId(sessionId);
+        const persistence = this.persistence;
+        if (persistence !== (void 0)) {
+            try {
+                persistence.deleteSession(id);
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+        this.sessions.delete(id);
+        this.sizes.delete(id);
+        this.loaded.delete(id);
+    }
+    partitionOf(sessionId) {
+        this.ensure(sessionId);
+        const existing = this.sessions.get(sessionId);
+        if (existing !== (void 0)) {
+            return existing;
+        }
+        const created = new Map();
+        this.sessions.set(sessionId, created);
+        this.sizes.set(sessionId, 0);
+        return created;
+    }
+    countOf(sessionId) {
+        const partition = this.sessions.get(sessionId);
+        if (partition === (void 0)) {
+            return 0;
+        }
+        let count = 0;
+        const buckets = [...partition.values()];
+        for (let index = 0; index < buckets.length; index += 1) {
+            count += buckets[index].size;
+        }
+        return count;
+    }
+    storedEntryIsValid(entry) {
+        if (entry === null || typeof (entry) !== "object") {
+            return false;
+        }
+        if (!nameIsValid(entry.namespace) || !nameIsValid(entry.key)) {
+            return false;
+        }
+        if (typeof (entry.updatedAt) !== "string" || entry.updatedAt.length === 0 || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0) {
+            return false;
+        }
+        let text;
+        try {
+            text = canonical(entry.value);
+        }
+        catch {
+            return false;
+        }
+        return Buffer.byteLength(text, "utf8") === entry.bytes;
+    }
+    persistPut(sessionId, entry) {
+        const persistence = this.persistence;
+        if (persistence === (void 0)) {
+            return;
+        }
+        try {
+            persistence.put(sessionId, clone(entry));
+        }
+        catch {
+            fail("store_failure");
+        }
+    }
+}

package/lib/session/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Closed error taxonomy for the session domain.
+ *
+ * Messages are the code itself. Root paths, agent ids, context keys and bearer
+ * tokens stay out of the error string so a transport can forward it to a model
+ * without leaking host layout or credentials.
+ */
+import type { SessionErrorCode } from "./types.js";
+/**
+ * One classified session failure. The message mirrors {@link code} exactly so
+ * an adapter never has to parse English prose and never receives a host path.
+ */
+export declare class SessionError extends Error {
+    readonly code: SessionErrorCode;
+    constructor(code: SessionErrorCode);
+}
+/**
+ * Throw one classified failure.
+ */
+export declare const fail: (code: SessionErrorCode) => never;
+/**
+ * Narrow an unknown thrown value to this domain's error.
+ */
+export declare const isSessionError: (error: unknown) => error is SessionError;

package/lib/session/errors.js

@@ -0,0 +1,22 @@
+/**
+ * One classified session failure. The message mirrors {@link code} exactly so
+ * an adapter never has to parse English prose and never receives a host path.
+ */
+export class SessionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "SessionError";
+        this.code = code;
+    }
+}
+/**
+ * Throw one classified failure.
+ */
+export const fail = (code) => {
+    throw new SessionError(code);
+};
+/**
+ * Narrow an unknown thrown value to this domain's error.
+ */
+export const isSessionError = (error) => error instanceof SessionError;

package/lib/session/identity.d.ts

@@ -0,0 +1,24 @@
+import type { SessionId } from "./types.js";
+/**
+ * Allocate a public session handle: `ses_` plus 32 lowercase hex characters.
+ */
+export declare const createSessionId: () => SessionId;
+/**
+ * Allocate a 32-byte bearer token encoded as base64url without padding.
+ */
+export declare const createSessionToken: () => string;
+/**
+ * Hash a token for storage as `sha256:<hex>`.
+ *
+ * The raw token never reaches the store; callers that persist the hash cannot
+ * reconstruct the secret from it.
+ */
+export declare const hashSessionToken: (token: string) => string;
+/**
+ * Compare a token against a stored `sha256:<hex>` digest in constant time.
+ *
+ * Both sides are copied into equal-width buffers before `timingSafeEqual`, so a
+ * length mismatch performs one comparison and returns `false` instead of
+ * throwing. A non-string argument is rejected the same way.
+ */
+export declare const verifySessionToken: (token: string, expectedHash: string) => boolean;

package/lib/session/identity.js

@@ -0,0 +1,56 @@
+/**
+ * Session identity generation and token verification.
+ *
+ * A session id is a public handle; the bearer token is the secret. Only the
+ * token hash is ever stored, and verification uses a constant-time comparison
+ * that still runs when the stored hash is missing, truncated or otherwise
+ * malformed, so a caller cannot learn the expected length from a throw.
+ */
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { fail } from "./errors.js";
+const SessionIdPrefix = "ses_";
+const SessionIdBytes = 16;
+const TokenBytes = 32;
+const HashPrefix = "sha256:";
+/**
+ * Allocate a public session handle: `ses_` plus 32 lowercase hex characters.
+ */
+export const createSessionId = () => `${SessionIdPrefix}${randomBytes(SessionIdBytes).toString("hex")}`;
+/**
+ * Allocate a 32-byte bearer token encoded as base64url without padding.
+ */
+export const createSessionToken = () => randomBytes(TokenBytes).toString("base64url");
+/**
+ * Hash a token for storage as `sha256:<hex>`.
+ *
+ * The raw token never reaches the store; callers that persist the hash cannot
+ * reconstruct the secret from it.
+ */
+export const hashSessionToken = (token) => {
+    if (typeof (token) !== "string") {
+        return fail("invalid_arguments");
+    }
+    return `${HashPrefix}${createHash("sha256").update(token, "utf8").digest("hex")}`;
+};
+/**
+ * Compare a token against a stored `sha256:<hex>` digest in constant time.
+ *
+ * Both sides are copied into equal-width buffers before `timingSafeEqual`, so a
+ * length mismatch performs one comparison and returns `false` instead of
+ * throwing. A non-string argument is rejected the same way.
+ */
+export const verifySessionToken = (token, expectedHash) => {
+    if (typeof (token) !== "string" || typeof (expectedHash) !== "string") {
+        return false;
+    }
+    const actual = Buffer.from(hashSessionToken(token), "utf8");
+    const expected = Buffer.from(expectedHash, "utf8");
+    const width = Math.max(actual.length, expected.length, 1);
+    const left = Buffer.alloc(width);
+    const right = Buffer.alloc(width);
+    actual.copy(left, 0);
+    expected.copy(right, 0);
+    const equal = timingSafeEqual(left, right);
+    return equal && actual.length === expected.length;
+};

package/lib/session/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public session entry: identity, lifecycle, context isolation and ports.
+ *
+ * `src/session` is the data-isolation boundary for one agent's workspace work.
+ * It is intentionally separate from `runtime/session.ts`, the cognitive memory
+ * of a turn loop, and it never shares mutable state with it.
+ */
+export { SessionError, fail, isSessionError } from "./errors.js";
+export { createSessionId, createSessionToken, hashSessionToken, verifySessionToken } from "./identity.js";
+export { SessionContexts } from "./context.js";
+export type { SessionContextOptions } from "./context.js";
+export { SessionRegistry } from "./registry.js";
+export type { SessionRotationStore } from "./registry.js";
+export * from "./types.js";

package/lib/session/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public session entry: identity, lifecycle, context isolation and ports.
+ *
+ * `src/session` is the data-isolation boundary for one agent's workspace work.
+ * It is intentionally separate from `runtime/session.ts`, the cognitive memory
+ * of a turn loop, and it never shares mutable state with it.
+ */
+export { SessionError, fail, isSessionError } from "./errors.js";
+export { createSessionId, createSessionToken, hashSessionToken, verifySessionToken } from "./identity.js";
+export { SessionContexts } from "./context.js";
+export { SessionRegistry } from "./registry.js";
+export * from "./types.js";