@armadra/agent 0.0.0-stage → 0.3.0

package/dist/agent/schema.js

@@ -0,0 +1,186 @@
+/**
+ * JSON Schema 子集校验（设计 §2、§5.1）。[B0] 所有。
+ *
+ * 子集：type（object / string / number / integer / boolean / array）、properties、required、
+ * additionalProperties（布尔）、items、enum（原始值）、description / title / default（只做注释）。
+ *
+ * - `validateSchema(schema, value)` 返回错误列表；空数组 = 通过。路径形如 `$.edits[0].oldText`，
+ *   非标识符键用 `$["a b"]`。
+ * - `checkSchemaSubset(schema)` 检查 schema 本身只用了子集关键字（工具注册时调用）。
+ * - 不做类型强转（"1" 不会当作 1），不填 default。
+ */
+const SCHEMA_TYPES = [
+    "object",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "array",
+];
+const SUPPORTED_KEYWORDS = new Set([
+    "type",
+    "title",
+    "description",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+    "default",
+]);
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+export function joinPath(base, key) {
+    if (typeof key === "number")
+        return `${base}[${key}]`;
+    return IDENTIFIER.test(key) ? `${base}.${key}` : `${base}[${JSON.stringify(key)}]`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return "non-finite number";
+        return Number.isInteger(value) ? "integer" : "number";
+    }
+    return typeof value;
+}
+function matchesType(type, value) {
+    switch (type) {
+        case "object":
+            return isPlainObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+    }
+}
+function formatEnum(values) {
+    return values.map((v) => JSON.stringify(v)).join(", ");
+}
+function validateAt(schema, value, path, out) {
+    if (schema.type !== undefined && !matchesType(schema.type, value)) {
+        out.push({
+            path,
+            keyword: "type",
+            message: `expected ${schema.type}, got ${describeValue(value)}`,
+        });
+        return;
+    }
+    if (schema.enum !== undefined && !schema.enum.some((candidate) => candidate === value)) {
+        out.push({
+            path,
+            keyword: "enum",
+            message: `must be one of ${formatEnum(schema.enum)}`,
+        });
+    }
+    if (isPlainObject(value) && (schema.type === "object" || schema.properties !== undefined)) {
+        const properties = schema.properties ?? {};
+        for (const key of schema.required ?? []) {
+            if (!Object.hasOwn(value, key) || value[key] === undefined) {
+                out.push({
+                    path: joinPath(path, key),
+                    keyword: "required",
+                    message: "is required",
+                });
+            }
+        }
+        for (const [key, child] of Object.entries(value)) {
+            const childSchema = Object.hasOwn(properties, key) ? properties[key] : undefined;
+            if (childSchema !== undefined) {
+                if (child !== undefined)
+                    validateAt(childSchema, child, joinPath(path, key), out);
+            }
+            else if (schema.additionalProperties === false) {
+                out.push({
+                    path: joinPath(path, key),
+                    keyword: "additionalProperties",
+                    message: "is not allowed",
+                });
+            }
+        }
+    }
+    if (Array.isArray(value) && schema.items !== undefined) {
+        const items = schema.items;
+        value.forEach((item, index) => validateAt(items, item, joinPath(path, index), out));
+    }
+}
+/** 校验 value；返回全部错误（不在第一处停下）。 */
+export function validateSchema(schema, value) {
+    const out = [];
+    validateAt(schema, value, "$", out);
+    return out;
+}
+/** 把错误列表格式化成给模型看的多行文本。 */
+export function formatSchemaErrors(errors) {
+    return errors.map((e) => `${e.path}: ${e.message}`).join("\n");
+}
+function checkSubsetAt(schema, path, out) {
+    if (!isPlainObject(schema)) {
+        out.push(`${path}: schema must be an object`);
+        return;
+    }
+    for (const key of Object.keys(schema)) {
+        if (!SUPPORTED_KEYWORDS.has(key))
+            out.push(`${path}: unsupported keyword "${key}"`);
+    }
+    const { type, properties, required, additionalProperties, items, enum: enumValues } = schema;
+    if (type !== undefined && !SCHEMA_TYPES.includes(type)) {
+        out.push(`${path}.type: unsupported type ${JSON.stringify(type)}`);
+    }
+    for (const key of ["title", "description"]) {
+        if (schema[key] !== undefined && typeof schema[key] !== "string") {
+            out.push(`${path}.${key}: must be a string`);
+        }
+    }
+    if (properties !== undefined) {
+        if (!isPlainObject(properties)) {
+            out.push(`${path}.properties: must be an object`);
+        }
+        else {
+            for (const [key, child] of Object.entries(properties)) {
+                checkSubsetAt(child, joinPath(`${path}.properties`, key), out);
+            }
+        }
+    }
+    if (required !== undefined) {
+        if (!Array.isArray(required) || !required.every((r) => typeof r === "string")) {
+            out.push(`${path}.required: must be an array of strings`);
+        }
+        else if (isPlainObject(properties)) {
+            for (const name of required) {
+                if (!Object.hasOwn(properties, name)) {
+                    out.push(`${path}.required: "${name}" is not declared in properties`);
+                }
+            }
+        }
+    }
+    if (additionalProperties !== undefined && typeof additionalProperties !== "boolean") {
+        out.push(`${path}.additionalProperties: only boolean is supported`);
+    }
+    if (items !== undefined)
+        checkSubsetAt(items, `${path}.items`, out);
+    if (enumValues !== undefined) {
+        const ok = Array.isArray(enumValues) &&
+            enumValues.length > 0 &&
+            enumValues.every((v) => v === null || ["string", "number", "boolean"].includes(typeof v));
+        if (!ok)
+            out.push(`${path}.enum: must be a non-empty array of primitives`);
+    }
+}
+/** 检查 schema 只用了子集关键字；返回问题列表，空数组 = 合规。 */
+export function checkSchemaSubset(schema) {
+    const out = [];
+    checkSubsetAt(schema, "$", out);
+    return out;
+}

package/dist/agent/session-cache.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 会话层缓存控制器（第三波 §1.2、§1.5–§1.7、§1.9、§1.10）。[W3-C1b]
+ *
+ * `wrapStream()` 包住会话的流函数：每次真实请求记一条 `RequestRecord`（内存）、算前缀指纹、
+ * 更新三态、检测未命中（发 `cache_miss`）、跨 70% / 90% 发 `context_pressure`，turn 请求完成后
+ * 交给保温状态机。摘要请求自成一条链，不与主链比对；压缩 / 分支摘要 / 档一裁剪 / `/tree`
+ * 之后的首个请求是重置点。子会话（depth > 0）有自己的控制器，`warmSubagents` 为 false 时不保温。
+ * fork 出的会话沿用根会话 id 作 `prompt_cache_key`（只是路由提示）；task 子会话不沿用。
+ */
+import { type CacheReportingTracker } from "../ai/cache/reporting.js";
+import type { RequestRecord, WarmingDecisionHandler, WarmingMode } from "../ai/cache/types.js";
+import { type WarmerTimers } from "../ai/cache/warmer.js";
+import type { CacheRetention, Model } from "../ai/types.js";
+import { type SummaryContinuation } from "../compaction/summarize-tier.js";
+import type { SessionManager } from "../session/manager.js";
+import type { StreamFn } from "./loop.js";
+import type { SessionCore } from "./session-core.js";
+import type { CacheSettings, SessionCacheStats } from "./types.js";
+export declare const DEFAULT_CACHE_SETTINGS: Readonly<CacheSettings>;
+export declare const PRESSURE_THRESHOLDS: readonly [70, 90];
+export declare function resolveCacheSettings(partial?: Partial<CacheSettings>): CacheSettings;
+export interface SessionCacheDeps {
+    now?(): number;
+    timers?: WarmerTimers;
+    /** 缺省进程内共享的 `sharedCacheReporting`。 */
+    tracker?: CacheReportingTracker;
+    /** 宿主 `cache.onWarmingDecision` 的处理器（每次刷新前现取）。 */
+    decider?(): WarmingDecisionHandler | undefined;
+}
+/** 目录 TTL（毫秒）：long 保留且有 long 档时用 long；无承诺 → undefined。 */
+export declare function cacheTtlMs(model: Model, retention?: CacheRetention): number | undefined;
+/** fork 链上的根会话 id（task 子会话与非 fork 会话用自己的 id）。 */
+export declare function cacheKeyOf(manager: SessionManager): string;
+export declare class SessionCacheController {
+    private readonly core;
+    private settings;
+    private readonly now;
+    private readonly tracker;
+    private readonly decider;
+    private readonly warmer;
+    private readonly models;
+    private readonly snapshots;
+    private readonly replaced;
+    private inner;
+    private warmingOverride;
+    private cacheKey;
+    private prev;
+    private lastTurnRecord;
+    private resetPending;
+    private disposed;
+    private activeTasks;
+    private taskSince;
+    private taskMs;
+    private readonly sums;
+    private missCount;
+    private readonly byReason;
+    private reBilledTokens;
+    private reBilledUsd;
+    private readonly growth;
+    private lastPercent;
+    private readonly subagents;
+    constructor(core: SessionCore, settings: CacheSettings, deps?: SessionCacheDeps);
+    /** 生效的保温模式：子会话在 warmSubagents 为 false 时 off；`/cache warm` 会话内覆盖。 */
+    mode(): WarmingMode;
+    get cacheSettings(): Readonly<CacheSettings>;
+    setWarming(mode: WarmingMode): void;
+    /** 最后一条 turn 请求（摘要续写的前缀依据）。 */
+    get lastTurn(): RequestRecord | undefined;
+    wrapStream(inner: StreamFn): StreamFn;
+    /** 会话事件（AgentSessionImpl.emit 转交）。 */
+    onEvent(event: Parameters<SessionCore["emit"]>[0]): void;
+    onAgentSettled(): void;
+    /** 压缩 / context_edit / setModel / navigate 之后：下一条请求是重置点，保温作废。 */
+    onContextChanged(): void;
+    /** task 子会话结束时由父会话汇总（各自独立统计）。 */
+    addSubagent(tokens: {
+        cacheRead: number;
+        prompt: number;
+    }, reBilledTokens: number): void;
+    stats(context?: {
+        tokens?: number | undefined;
+        window?: number | undefined;
+    }): SessionCacheStats;
+    /**
+     * 摘要续写的前缀（第三波 §1.8）：当前转录按回合同样的方式转换，且上一次 turn 请求的消息
+     * 逐条是它的前缀（缓存必然命中）、加上摘要输出放得进窗口；否则 undefined（走独立请求）。
+     */
+    summaryContinuation(): SummaryContinuation | undefined;
+    dispose(): void;
+    private modelOf;
+    private toolsKey;
+    private takeTaskMs;
+    private turnsLeft;
+    private observe;
+    private checkPressure;
+    private scheduleWarm;
+    private isCurrent;
+    private replay;
+    private onWarmed;
+}