@sema-agent/server 2.0.0 → 3.0.0

package/dist/boot/budget-tracing.js

@@ -0,0 +1,86 @@
+/**
+ * design/158 A10:composition root 分段 —— 计费/追踪/预算装配(brain、pricing、cost quota、
+ * usage tracker、fleet lease、tracer、side-query 记账、offload/policy/snapshot 三个 core 店)。
+ *
+ * 纯搬运:函数体逐字来自 `main.ts`(原 933-995 行),缩进不变;新增的只有 import 与包壳。
+ *
+ * ⚠️ **位置即契约**:`tracer` 与 `sideQueryAccounting` 必须共用**同一组 sink 实例**
+ * (costQuota/fleetUsage/fleetLease/modelUsageTracker),故两者同段构造、不可拆到两处各造一份。
+ * `breakerState` 由 stores 段先行产出(brain 要它),所以本段排在 stores 之后。
+ */
+import { createBrain } from "../brain.js";
+import { ModelUsageTracker, PromptManifestTracker, buildPricing, createSideQueryAccountant, createTracer } from "../budget.js";
+import { FleetUsageAccumulator } from "../fleet-client.js";
+import { createFleetLeaseFromEnv } from "../fleet-lease.js";
+import { CostQuota } from "../observability/cost-quota.js";
+export function createBudgetAndTracing(ctx) {
+    const { config, logger, metrics, backend, breakerState } = ctx;
+    const brain = createBrain(config, { breakerState });
+    // ③ Cost + ④ trace + ⑤ budget (1.37): inject per-model pricing (authoritative costMicroUsd), bridge
+    //    core's content-free trace events to /metrics, and accumulate per-principal spend into the cost
+    //    quota (the tracer reads the principal ALS so council/team sub-task cost is attributed too).
+    const pricing = buildPricing(config.models);
+    // S9 (SILENT-FALLBACK P0-e): write-behind flush/refresh failures previously vanished in a bare catch —
+    // the fleet silently degrades to per-replica counting (soft limits stop being fleet-wide). Every failure
+    // ticks the counter + streak gauge; warn once per episode (streak hits 3), info on the recovery edge.
+    const counterDegradeHook = (info) => {
+        metrics.setGauge("counter_flush_fail_streak", info.streak, { table: info.table, kind: info.kind });
+        if (info.streak > 0)
+            metrics.inc("counter_flush_failed_total", { table: info.table, kind: info.kind });
+        if (info.streak === 3)
+            logger.warn("counter_flush_degraded", { table: info.table, kind: info.kind, streak: info.streak, ...(info.error ? { error: info.error } : {}) });
+        else if (info.streak === 0 && info.prevStreak >= 3)
+            logger.info("counter_flush_recovered", { table: info.table, kind: info.kind, prevStreak: info.prevStreak });
+    };
+    // Per-principal cumulative cost quota: TiDB-backed (cross-replica, atomic write-behind) when a pool
+    // exists, else in-memory per-replica (single-replica / no DB). Both satisfy QuotaTracker. (design/30 P0-1)
+    const costQuota = config.maxPrincipalCostUsd > 0
+        ? backend?.costQuota // local omits costQuota() → in-memory per-process CostQuota (single-replica)
+            ? backend.costQuota(Math.round(config.maxPrincipalCostUsd * 1e6), config.costQuotaWindowSec * 1000, counterDegradeHook).startRefresh()
+            : new CostQuota(Math.round(config.maxPrincipalCostUsd * 1e6), config.costQuotaWindowSec * 1000)
+        : undefined;
+    // E8 (shell-host contract): per-task × per-model usage accumulator, fed by the tracer and drained by the durable run
+    // lifecycle into `model_usage` events (the `TaskStats.modelUsage` echo). One instance, shared tracer↔server.
+    const modelUsageTracker = new ModelUsageTracker();
+    // [998]② web 观测切片 A 数据面:prompt.assembled 的 manifest 经 tracer 记录、由 durable run 生命周期
+    // drain 成 `prompt_assembled` 事件(turns/stream 可读)。与 modelUsageTracker 同款 register 篱笆/生命周期。
+    const promptManifestTracker = new PromptManifestTracker();
+    // fleet 用量批报的 principal×model 窗口累计器 — 仅当 fleet 面可能启用(center lane 配置了)才建,
+    // 否则 tracer 走 undefined = 零行为(非 fleet 部署不多攒一份内存)。真正的启动门在 startFleetClientFromEnv。
+    const fleetUsage = config.configCenter && process.env.FLEET_ADVERTISE_ADDRESS ? new FleetUsageAccumulator() : undefined;
+    // fleet lease 消费(worker 侧第三接线,D4 AP 模式):协商式 —— center lane 配齐即启(lease 是出站消费面,
+    // 不需要 FLEET_ADVERTISE_ADDRESS);非 lease-enforced principal 一次 409 负缓存后走既有本地 CostQuota,
+    // 单用户(无 principal)提交门早退 —— 两者零行为变化。
+    const fleetLease = createFleetLeaseFromEnv(config, { logger, metrics });
+    // weight-at-burn 回调:读 config.modelQuotaWeights(registry hot-apply 的活表;env lane 空 ⇒ 1 兜底)。
+    const tracer = createTracer(metrics, costQuota, modelUsageTracker, fleetUsage, fleetLease, (m) => config.modelQuotaWeights[m] ?? 1, promptManifestTracker);
+    // [1469] side-query 记账 seam:与 tracer 同一装配点、同一组 sink 实例(codex R3——sideQuery 不发
+    // brain.call,四路 sink 必须由 server 半场喂,两臂同语义见 createSideQueryAccountant 头注)。
+    const sideQueryAccounting = createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetLease, (m) => config.modelQuotaWeights[m] ?? 1);
+    // Durable offload store (core 1.47/1.49): large tool results survive a cross-replica wake. Without a
+    // pool, core's task-scoped in-memory default applies (graceful: cross-wake fetch misses → preview stands).
+    const toolResultStore = backend?.toolResult ? backend.toolResult() : undefined; // tidb/pg = SQL twins; local = core's FileToolResultStore (core 1.219 — restart-durable refs); no backend → core's in-memory default
+    // E6 durable SessionPolicyStore — operator-tightened per-session tool rules core reads at prepare-time (subtract-only).
+    // Present on every backend (incl local = core's InMemorySessionPolicyStore); undefined only on the env-only/no-backend
+    // worker → feature OFF (core reads no rules). Wired into the PRIMARY Runner below + the PUT/GET policy route + E21 purge.
+    const sessionPolicyStore = backend ? backend.sessionPolicy() : undefined;
+    // E19 rewind-files — working-tree snapshot/restore keyed by entryId (the same anchor as E18), + the 2c artifact-transfer
+    // store. core AUTOMATICALLY snapshots each completed turn + restores on resumeAt when `spec.rewindFiles` is set, for ANY
+    // ExecutionEnv when this store is wired (gate-split 1.134.0 removed the isRemoteExecutionEnv skip → host/local-mode
+    // + e2b/k8s/ssh/adb/local-docker all active). Durable on tidb/pg (cross-replica + 2c), local = core's
+    // InMemoryFileSnapshotStore. Wired into the PRIMARY Runner + the `rewindFiles` cap + E21 purge.
+    const fileSnapshotStore = backend ? backend.fileSnapshot() : undefined;
+    // [805]③a / [806]④: E19-fix observability — core 1.287 captureManifest TOLERATES enumerate→read-window
+    // vanished files (skip, not fail) and reports the count ONLY in its return value; the SQL twins expose it via
+    // this optional sink. Metric = the live face of "the fix is absorbing real races" (a warn would be noise — the
+    // skip is the CORRECT behavior). GAP (honest): the local lane uses core's own store, which drops the count
+    // internally — surfacing it there needs a core seam (noted on the board, not faked here).
+    if (fileSnapshotStore && "onSkippedVanished" in fileSnapshotStore) {
+        fileSnapshotStore.onSkippedVanished = (count) => metrics.inc("snapshot_skipped_vanished_total", {}, count);
+    }
+    return {
+        brain, pricing, counterDegradeHook, costQuota, modelUsageTracker, promptManifestTracker,
+        fleetUsage, fleetLease, tracer, sideQueryAccounting, toolResultStore, sessionPolicyStore, fileSnapshotStore,
+    };
+}
+//# sourceMappingURL=budget-tracing.js.map

package/dist/boot/config-center.d.ts

@@ -0,0 +1,62 @@
+import { CenterPromptSource, type Model } from "@sema-agent/core";
+import { buildPricing } from "../budget.js";
+import { type PromptsDomainFaces } from "../capabilities/center-prompts.js";
+import { type Scenario, type ScenarioDeps, type ScenarioDetail } from "../capabilities/scenarios.js";
+import type { LoadedSkill } from "../capabilities/skills.js";
+import { type ServiceConfig } from "../config.js";
+import type { Logger } from "../observability/logger.js";
+import type { Metrics } from "../observability/metrics.js";
+import { type RestartSignal } from "../sema-registry.js";
+export interface ConfigCenterRuntimeCtx {
+    config: ServiceConfig;
+    logger: Logger;
+    metrics: Metrics;
+    /** 🔴 与 main 的 remoteExec loader 共用的**同一个**本地根(split-brain 防线,理由见 main.ts 构造点)。 */
+    localRoot: string;
+}
+/** center scenarios overlay 的活引用面(overlay 就地写进 main 持有的两张表)。 */
+export interface CenterScenarioOverlayTargets {
+    scenarioDeps: ScenarioDeps;
+    scenarios: Record<string, Scenario>;
+    scenarioDetails: Record<string, ScenarioDetail>;
+    /** overlay 前捕获的六内建名(centerScenarioDetails 的 shadow 判据)。 */
+    builtinScenarioNames: string[];
+}
+/** 跨段可变状态的**唯一**对外读口 + 三个原位动作。字段语义见各方法上的注释。 */
+export interface ConfigCenterRuntime {
+    /** 配置源形态;`undefined` = 纯 env 部署(本运行时的所有分支不存在)。 */
+    readonly providerKind: "remote" | "local" | undefined;
+    /** core `CenterPromptSource`(RunnerDeps / subRunner 必须同实例)。 */
+    readonly promptSource: CenterPromptSource;
+    /** DUAL-MODE §4/§5:local 形从 `config.d/remote-exec.json` 覆写 `config.remoteExec`(坏文件 = fail-closed 抛)。 */
+    applyLocalRemoteExec(): Promise<void>;
+    /** center skills overlay → plugins 消费 → boot LKG 落盘/skill-stale 判定 → mcp 解析。返回新的 skills 表。 */
+    applyCenterCapabilities(skills: LoadedSkill[]): Promise<LoadedSkill[]>;
+    /** center 声明场景 overlay(就地写进传入的两张表)。 */
+    applyCenterScenarios(t: CenterScenarioOverlayTargets): void;
+    /** per-model key resolver 首建(原位调用,见文件头注 5)。 */
+    initKeyResolver(): void;
+    /** 60s refresh cadence + boot-deferred 到货续接。 */
+    startRefreshLoop(a: {
+        runnerTierFrozen: boolean;
+        pricing: ReturnType<typeof buildPricing>;
+    }): void;
+    /** 晚绑取值:refresh 热应用会整个换引用(hook LLM / resolveSpec 每次现取)。 */
+    getKeyResolver(): ((model: Model) => Promise<{
+        apiKey: string;
+    } | undefined>) | undefined;
+    /** 晚绑取值:center 提示词面(热采用,新任务边界生效)。 */
+    getCenterPrompts(): PromptsDomainFaces | undefined;
+    /** boot ready 门:roster 未落地 = 计费提交 503 + /health ready:false。 */
+    modelReady(): boolean;
+    /** /health.restart(orchestrator 自动重启信号)。 */
+    restartState(): RestartSignal | undefined;
+    /** /health.modelPlaneDeferred(codex R18 卡死的 plane,无 next-boot handoff)。 */
+    planeDeferredState(): {
+        version: number;
+        since: number;
+        blocked?: string[];
+    } | undefined;
+}
+export declare function createConfigCenterRuntime(ctx: ConfigCenterRuntimeCtx): Promise<ConfigCenterRuntime>;
+//# sourceMappingURL=config-center.d.ts.map