@nathapp/nax-agent 0.91.7 → 0.91.8-canary.1

package/dist/memory/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The memory note model — the shapes and limits shared by the note codec, the
+ * mirror store, the index renderer, the providers and the sync loop.
+ *
+ * A note is one Markdown file with frontmatter (`note.ts` writes and reads it);
+ * a decision is one line of the mirror's read-only `decisions.jsonl`; a hit is
+ * one keyword-search result; a timers object is the race seam the sync loop
+ * injects in tests.
+ */
+export declare const MEMORY_NOTE_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryNoteType = (typeof MEMORY_NOTE_TYPES)[number];
+export declare const MEMORY_SCOPES: readonly ["project", "user"];
+export type MemoryScope = (typeof MEMORY_SCOPES)[number];
+export declare const MEMORY_NOTE_STATUSES: readonly ["active", "pending", "superseded", "rejected", "deleted"];
+export type MemoryNoteStatus = (typeof MEMORY_NOTE_STATUSES)[number];
+export declare const MEMORY_DECISION_STATUSES: readonly ["active", "superseded", "rejected"];
+export type MemoryDecisionStatus = (typeof MEMORY_DECISION_STATUSES)[number];
+export interface MemoryNote {
+    readonly id: string;
+    readonly slug: string;
+    readonly type: MemoryNoteType;
+    readonly scope: MemoryScope;
+    readonly description: string;
+    readonly source: string;
+    readonly updatedAt: string;
+    readonly status: MemoryNoteStatus;
+    readonly body: string;
+}
+export interface MemoryDecision {
+    readonly id: string;
+    readonly subject: string;
+    readonly predicate: string;
+    readonly object: string;
+    readonly updatedAt: string;
+    readonly status: MemoryDecisionStatus;
+}
+export interface MemoryHit {
+    readonly slug: string;
+    readonly scope: MemoryScope;
+    readonly type: MemoryNoteType;
+    readonly description: string;
+    readonly status: MemoryNoteStatus;
+    readonly score: number;
+    readonly snippet: string;
+}
+export interface MemoryNoteWrite {
+    readonly slug: string;
+    readonly type: MemoryNoteType;
+    readonly scope: MemoryScope;
+    readonly description: string;
+    readonly body: string;
+}
+export interface MemoryWriteRefusal {
+    readonly field: "slug" | "type" | "description" | "body" | "source" | "reason";
+    readonly reason: string;
+}
+export interface MemoryTimers {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(id: unknown): void;
+}
+/** A note slug: 1-64 characters, lower-case alphanumerics and interior `-`. */
+export declare const MEMORY_SLUG_RE: RegExp;
+/** An outbox client id: 1-128 letters, digits, `_` or `-`. */
+export declare const MEMORY_CLIENT_ID_RE: RegExp;
+export declare const MEMORY_NOTE_BODY_MAX_BYTES = 8192;
+export declare const MEMORY_DESCRIPTION_MAX_CHARS = 200;
+export declare const MEMORY_SOURCE_MAX_CHARS = 64;
+/**
+ * The longest justification a forget may carry.
+ *
+ * A reason is a one-line answer to "why did this note go", and it is persisted twice over: on
+ * the request the provider is pushed, and inside the outbox entry a forget that cannot be
+ * delivered leaves behind. Bounding it here — the same cap as a note's description, because it
+ * is the same kind of text — keeps a terminal or a step from filling the mirror's queue with a
+ * justification of its own making. `forgetReasonRefusal` is where the rule is applied to a
+ * forget, and the outbox applies that same rule when it takes a request, so the queue never
+ * holds one it cannot replay. An entry already on disk is read whatever its reason's length:
+ * the bound is a condition on writing, not on reading.
+ */
+export declare const MEMORY_FORGET_REASON_MAX_CHARS = 200;
+export declare const MEMORY_INDEX_MAX_BYTES = 24576;
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+export declare const MEMORY_INDEX_MIN_LINES = 16;
+export declare const MEMORY_INDEX_MIN_BYTES = 512;
+export declare const MEMORY_PROBE_TIMEOUT_MS = 2000;
+export declare const MEMORY_OP_TIMEOUT_MS = 10000;
+export declare const MEMORY_PULL_PAGE_SIZE = 200;
+export declare const MEMORY_PULL_MAX_PAGES = 50;
+/**
+ * The key a note is addressed by wherever the mirror and the queue meet: `<scope>/<slug>`.
+ *
+ * The outbox holds writes by this key and a save asks the outbox whether the key it is
+ * about to write is already held, so the two spellings have to be one: a save that asks
+ * with a different key would never see the entry it must queue behind.
+ */
+export declare function memoryNoteKey(scope: MemoryScope, slug: string): string;

package/dist/memory/types.js

@@ -0,0 +1,51 @@
+/**
+ * The memory note model — the shapes and limits shared by the note codec, the
+ * mirror store, the index renderer, the providers and the sync loop.
+ *
+ * A note is one Markdown file with frontmatter (`note.ts` writes and reads it);
+ * a decision is one line of the mirror's read-only `decisions.jsonl`; a hit is
+ * one keyword-search result; a timers object is the race seam the sync loop
+ * injects in tests.
+ */
+export const MEMORY_NOTE_TYPES = ["user", "feedback", "project", "reference"];
+export const MEMORY_SCOPES = ["project", "user"];
+export const MEMORY_NOTE_STATUSES = ["active", "pending", "superseded", "rejected", "deleted"];
+export const MEMORY_DECISION_STATUSES = ["active", "superseded", "rejected"];
+/** A note slug: 1-64 characters, lower-case alphanumerics and interior `-`. */
+export const MEMORY_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** An outbox client id: 1-128 letters, digits, `_` or `-`. */
+export const MEMORY_CLIENT_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+export const MEMORY_NOTE_BODY_MAX_BYTES = 8192;
+export const MEMORY_DESCRIPTION_MAX_CHARS = 200;
+export const MEMORY_SOURCE_MAX_CHARS = 64;
+/**
+ * The longest justification a forget may carry.
+ *
+ * A reason is a one-line answer to "why did this note go", and it is persisted twice over: on
+ * the request the provider is pushed, and inside the outbox entry a forget that cannot be
+ * delivered leaves behind. Bounding it here — the same cap as a note's description, because it
+ * is the same kind of text — keeps a terminal or a step from filling the mirror's queue with a
+ * justification of its own making. `forgetReasonRefusal` is where the rule is applied to a
+ * forget, and the outbox applies that same rule when it takes a request, so the queue never
+ * holds one it cannot replay. An entry already on disk is read whatever its reason's length:
+ * the bound is a condition on writing, not on reading.
+ */
+export const MEMORY_FORGET_REASON_MAX_CHARS = 200;
+export const MEMORY_INDEX_MAX_BYTES = 24_576;
+export const MEMORY_INDEX_MAX_LINES = 200;
+export const MEMORY_INDEX_MIN_LINES = 16;
+export const MEMORY_INDEX_MIN_BYTES = 512;
+export const MEMORY_PROBE_TIMEOUT_MS = 2000;
+export const MEMORY_OP_TIMEOUT_MS = 10_000;
+export const MEMORY_PULL_PAGE_SIZE = 200;
+export const MEMORY_PULL_MAX_PAGES = 50;
+/**
+ * The key a note is addressed by wherever the mirror and the queue meet: `<scope>/<slug>`.
+ *
+ * The outbox holds writes by this key and a save asks the outbox whether the key it is
+ * about to write is already held, so the two spellings have to be one: a save that asks
+ * with a different key would never see the entry it must queue behind.
+ */
+export function memoryNoteKey(scope, slug) {
+    return `${scope}/${slug}`;
+}

package/dist/memory/validate.d.ts

@@ -0,0 +1,31 @@
+import { type MemoryNoteWrite, type MemoryWriteRefusal } from "./types.ts";
+/**
+ * The write as received. `type` stays `string` because the value arrives from
+ * an agent tool call: narrowing it in the type system would leave the runtime
+ * check unreachable without a cast in the very test that has to exercise it.
+ */
+export type MemoryNoteWriteInput = Omit<MemoryNoteWrite, "type"> & {
+    readonly type: string;
+};
+/**
+ * The first secret-shaped run in `text`, as its pattern's `kind` label. Every
+ * pattern carries the `/g` flag (the logger needs it for `replace`), so
+ * `lastIndex` is reset before each scan — otherwise a second call would resume
+ * where the first stopped and skip a match.
+ */
+export declare function findSecret(text: string): {
+    readonly kind: string;
+} | null;
+/**
+ * The refusal for a forget's reason, or `null` when it may be recorded.
+ *
+ * A reason is what a later session reads to know why a note went, so it is held to the same
+ * one-line, non-empty, length-capped rule as a note's description: it is persisted on the
+ * request and inside a queued entry, and neither of those is a place to keep an essay.
+ */
+export declare function forgetReasonRefusal(reason: string): MemoryWriteRefusal | null;
+/**
+ * The refusal for a note write, or `null` when it may be stored. Stops at the
+ * first problem, in the design's order, so the caller reports one reason.
+ */
+export declare function validateMemoryNoteWrite(write: MemoryNoteWriteInput, source: string): MemoryWriteRefusal | null;

package/dist/memory/validate.js

@@ -0,0 +1,104 @@
+/**
+ * Write validation — the check a save runs before anything is persisted.
+ *
+ * `validateMemoryNoteWrite` answers one question for the save path
+ * (`operations.ts`): may this note be stored at all? It returns `null` when it
+ * may, or the first `MemoryWriteRefusal` it found, checking in the design's
+ * order: slug, type, description, source, body size, then secrets.
+ *
+ * `findSecret` is the secret half on its own: it runs the logger's
+ * `SECRET_VALUE_PATTERNS` over free text and reports the kind of the first
+ * accepted match. Both functions are pure — no file, no logger, no I/O — so the
+ * refusal text is all the caller has to work with, and it never contains the
+ * matched text.
+ */
+import { SECRET_VALUE_PATTERNS } from "#src/internal/redact";
+import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_TYPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, } from "./types.js";
+/** A one-line field may carry no line break and no ASCII control character (a tab or DEL included). */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point of this check
+const CONTROL_OR_LINE_BREAK = /[\u0000-\u001f\u007f]/;
+function isMemoryNoteType(value) {
+    return MEMORY_NOTE_TYPES.some((type) => type === value);
+}
+function slugRefusal(slug) {
+    if (MEMORY_SLUG_RE.test(slug))
+        return null;
+    return { field: "slug", reason: 'slug must be 1-64 lower-case letters, digits or "-"' };
+}
+function typeRefusal(type) {
+    if (isMemoryNoteType(type))
+        return null;
+    return { field: "type", reason: `type must be one of ${MEMORY_NOTE_TYPES.join(", ")}` };
+}
+/** The shared check for `description` and `source`: non-empty, one line, at most `maxChars`. */
+function lineRefusal(field, text, maxChars) {
+    if (text === "")
+        return { field, reason: `${field} must not be empty` };
+    if (CONTROL_OR_LINE_BREAK.test(text)) {
+        return { field, reason: `${field} must not contain a line break or control character` };
+    }
+    if (text.length > maxChars)
+        return { field, reason: `${field} must be at most ${maxChars} characters` };
+    return null;
+}
+/** The body cap counts UTF-8 bytes, so a multi-byte body can fail below the character limit. */
+function bodyRefusal(body) {
+    if (Buffer.byteLength(body, "utf8") <= MEMORY_NOTE_BODY_MAX_BYTES)
+        return null;
+    return { field: "body", reason: `body must be at most ${MEMORY_NOTE_BODY_MAX_BYTES} bytes` };
+}
+/**
+ * A refusal when `text` carries a secret. The reason names the pattern's kind
+ * and never the matched text: a refusal is shown to the agent and logged.
+ */
+function secretRefusal(field, text) {
+    const secret = findSecret(text);
+    return secret === null ? null : { field, reason: `secret (${secret.kind}) must not be stored` };
+}
+/**
+ * The first secret-shaped run in `text`, as its pattern's `kind` label. Every
+ * pattern carries the `/g` flag (the logger needs it for `replace`), so
+ * `lastIndex` is reset before each scan — otherwise a second call would resume
+ * where the first stopped and skip a match.
+ */
+export function findSecret(text) {
+    for (const { kind, re, acceptMatch } of SECRET_VALUE_PATTERNS) {
+        re.lastIndex = 0;
+        let match = re.exec(text);
+        while (match !== null) {
+            const matched = match[0];
+            // A zero-length match would leave `lastIndex` unchanged and spin forever.
+            if (matched === "") {
+                re.lastIndex += 1;
+            }
+            else if (acceptMatch === undefined || acceptMatch(matched)) {
+                return { kind };
+            }
+            match = re.exec(text);
+        }
+    }
+    return null;
+}
+/**
+ * The refusal for a forget's reason, or `null` when it may be recorded.
+ *
+ * A reason is what a later session reads to know why a note went, so it is held to the same
+ * one-line, non-empty, length-capped rule as a note's description: it is persisted on the
+ * request and inside a queued entry, and neither of those is a place to keep an essay.
+ */
+export function forgetReasonRefusal(reason) {
+    return lineRefusal("reason", reason, MEMORY_FORGET_REASON_MAX_CHARS);
+}
+/**
+ * The refusal for a note write, or `null` when it may be stored. Stops at the
+ * first problem, in the design's order, so the caller reports one reason.
+ */
+export function validateMemoryNoteWrite(write, source) {
+    return (slugRefusal(write.slug) ??
+        typeRefusal(write.type) ??
+        lineRefusal("description", write.description, MEMORY_DESCRIPTION_MAX_CHARS) ??
+        lineRefusal("source", source, MEMORY_SOURCE_MAX_CHARS) ??
+        bodyRefusal(write.body) ??
+        secretRefusal("description", write.description) ??
+        secretRefusal("body", write.body));
+}

package/dist/session-store/index.d.ts

@@ -1,3 +1,3 @@
-export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
+export { acquireSessionLock, LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.ts";
 export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, type SessionMeta, type SessionMetaMode, } from "./session-meta.ts";
 export { createSessionStorage, LIST_PAGE_SIZE, processAlive, type SessionListEntry, type SessionListPage, type SessionLockHolder, type SessionLockHolderState, type SessionStorage, type SessionStorageDeps, } from "./storage.ts";

package/dist/session-store/index.js

@@ -1,3 +1,3 @@
-export { LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
+export { acquireSessionLock, LOCK_HEARTBEAT_MS, LOCK_STALE_MS } from "./session-lock.js";
 export { defaultSessionsDir, SESSION_ID_PATTERN, SESSION_META_MODES, } from "./session-meta.js";
 export { createSessionStorage, LIST_PAGE_SIZE, processAlive, } from "./storage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax-agent",
-  "version": "0.91.7",
+  "version": "0.91.8-canary.1",
   "description": "nax's native coding agent: session contract, native loop, tools, permissions, sandbox, command-safety.",
   "license": "MIT",
   "author": "William Khoo",
@@ -47,13 +47,13 @@
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.77",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@nathapp/nax-ai": "0.91.7",
+    "@nathapp/nax-ai": "0.91.8-canary.1",
     "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
     "provenance": true,
-    "tag": "latest"
+    "tag": "canary"
   }
 }