@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/evals/snapshot.js

@@ -0,0 +1,207 @@
+import { normalizeStoredDefinition } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+import { childRunDefinition } from "../runtime/subagents/definition.js";
+/** The follow-up narrowing on the last sub-agent task message of `events`, if any. */
+function lastTaskNarrowing(events) {
+    const task = events.findLast((e) => e.type === "user_message" && e.payload.dispatch !== undefined);
+    return task?.payload?.dispatch?.narrowed;
+}
+const TERMINAL = new Set(["run_finished", "run_failed", "run_aborted"]);
+/** 读事件的分页大小。 */
+const PAGE = 1000;
+/**
+ * 给某次运行建用例快照。会话不在该组织、或运行不属于该会话 → `conversation.not_found`；
+ * 运行还没有终态事件 → `eval.run_not_finished`（409）；序列化后超过 `maxBytes` 字节 → `eval.case_too_large`（413）。
+ * `maxBytes` 由调用方传入（`evals.maxCaseBytes`）。
+ */
+export async function takeSnapshot(db, orgId, conversationId, runId, maxBytes) {
+    const conv = await db
+        .selectFrom("conversations")
+        .select(["agent_id", "kind"])
+        .where("id", "=", conversationId)
+        .where("org_id", "=", orgId)
+        .executeTakeFirst();
+    const run = conv
+        ? await db
+            .selectFrom("runs")
+            .select("agent_version")
+            .where("id", "=", runId)
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst()
+        : undefined;
+    if (!conv || !run) {
+        throw new ApiError("conversation.not_found", "Conversation or run not found");
+    }
+    const end = await db
+        .selectFrom("conversation_events")
+        .select("seq")
+        .where("conversation_id", "=", conversationId)
+        .where("run_id", "=", runId)
+        .where("type", "in", [...TERMINAL])
+        .orderBy("seq")
+        .executeTakeFirst();
+    if (!end)
+        throw new ApiError("eval.run_not_finished", "The run has not finished yet");
+    const endSeq = Number(end.seq);
+    const tooLarge = () => new ApiError("eval.case_too_large", `The run's snapshot is larger than the ${maxBytes}-byte limit`);
+    const events = [];
+    /** 已读事件序列化后的字节数（快照总大小的下界）：一超过上限就停，不把超大的对话整个读进内存。 */
+    let bytes = 0;
+    let after = 0;
+    for (;;) {
+        const rows = await db
+            .selectFrom("conversation_events")
+            .select(["seq", "type", "run_id", "payload", "created_at"])
+            .where("conversation_id", "=", conversationId)
+            .where("seq", ">", String(after))
+            .where("seq", "<=", String(endSeq))
+            .orderBy("seq")
+            .limit(PAGE)
+            .execute();
+        for (const r of rows) {
+            const e = {
+                seq: Number(r.seq),
+                type: r.type,
+                payload: r.payload,
+                runId: r.run_id,
+                createdAt: new Date(r.created_at).toISOString(),
+            };
+            bytes += Buffer.byteLength(JSON.stringify(e));
+            if (bytes > maxBytes)
+                throw tooLarge();
+            events.push(e);
+        }
+        const last = rows.at(-1);
+        if (rows.length < PAGE || !last)
+            break;
+        after = Number(last.seq);
+    }
+    const versions = new Set([run.agent_version]);
+    const hashes = new Set();
+    for (const e of events) {
+        if (e.type === "run_started") {
+            versions.add(e.payload.agentVersion);
+        }
+        else if (e.type === "model_call") {
+            const req = e.payload.request;
+            for (const t of [...(req.tools ?? []), ...(req.catalog ?? [])])
+                hashes.add(t.specHash);
+        }
+    }
+    const definitions = {};
+    const defRows = await db
+        .selectFrom("agent_versions")
+        .select(["version", "definition"])
+        .where("agent_id", "=", conv.agent_id)
+        .where("version", "in", [...versions])
+        .orderBy("version")
+        .execute();
+    for (const r of defRows) {
+        definitions[String(r.version)] = normalizeStoredDefinition(r.definition);
+    }
+    const toolSpecs = {};
+    if (hashes.size > 0) {
+        const specRows = await db
+            .selectFrom("tool_specs")
+            .select(["spec_hash", "spec"])
+            .where("spec_hash", "in", [...hashes].sort())
+            .orderBy("spec_hash")
+            .execute();
+        for (const r of specRows)
+            toolSpecs[r.spec_hash] = r.spec;
+    }
+    const started = events.find((e) => e.type === "subagent_started")?.payload;
+    const invokedSkill = started?.template.invokedSkill;
+    const dispatch = conv.kind === "subagent"
+        ? await db
+            .selectFrom("subagent_dispatches")
+            .select(["parent_conversation_id", "parent_run_id", "parent_call_id"])
+            .where("child_run_id", "=", runId)
+            .executeTakeFirst()
+        : undefined;
+    const snapshot = {
+        version: 1,
+        orgId,
+        conversationId,
+        runId,
+        agentId: conv.agent_id,
+        agentVersion: run.agent_version,
+        events,
+        definitions,
+        toolSpecs,
+        ...(started !== undefined && {
+            subagent: {
+                // this run's definition: the frozen one with its follow-up's narrowing (final review
+                // I1); the run's task message is the last one up to its terminal event
+                definition: childRunDefinition(normalizeStoredDefinition(started.definition), lastTaskNarrowing(events)),
+                preamble: started.preamble,
+                ...(invokedSkill !== undefined && { invokedSkill }),
+            },
+        }),
+        ...(dispatch !== undefined && {
+            parent: {
+                conversationId: dispatch.parent_conversation_id,
+                runId: dispatch.parent_run_id,
+                callId: dispatch.parent_call_id,
+            },
+        }),
+    };
+    if (Buffer.byteLength(JSON.stringify(snapshot)) > maxBytes)
+        throw tooLarge();
+    return snapshot;
+}
+/**
+ * 读出库里存的快照（`eval_cases.snapshot`）：把各版本定义里改名前（D17）的 `{ kind: "app" }` 工具引用规范化为
+ * connector 形（C27）。整轮回放会把定义交给实时注册表，不规范化的话连接器工具全部失效。其余字段原样。
+ */
+export function readSnapshot(raw) {
+    const s = raw;
+    const definitions = {};
+    for (const [v, d] of Object.entries(s.definitions ?? {})) {
+        definitions[v] = normalizeStoredDefinition(d);
+    }
+    return {
+        ...s,
+        definitions,
+        ...(s.subagent !== undefined && {
+            subagent: { ...s.subagent, definition: normalizeStoredDefinition(s.subagent.definition) },
+        }),
+    };
+}
+/** 快照事件还原为日志事件（`createdAt` 转回 Date）。 */
+export function toEvents(s) {
+    return s.events.map((e) => ({
+        conversationId: s.conversationId,
+        seq: e.seq,
+        type: e.type,
+        payload: e.payload,
+        runId: e.runId,
+        createdAt: new Date(e.createdAt),
+    }));
+}
+/**
+ * 快照运行里可单步回放的模型调用：每步的最后一次尝试（含收尾调用），且该步有回复（`assistant_message`）；
+ * 没有回复的步骤（尝试都失败）不在其中。按 seq 升序。
+ */
+export function replayableCalls(s) {
+    const lastCall = new Map();
+    const replies = new Map();
+    for (const e of s.events) {
+        if (e.runId !== s.runId)
+            continue;
+        if (e.type === "model_call") {
+            lastCall.set(e.payload.step, e.seq);
+        }
+        else if (e.type === "assistant_message") {
+            const step = e.payload.step;
+            replies.set(step, [...(replies.get(step) ?? []), e.seq]);
+        }
+    }
+    const out = [];
+    for (const [step, seq] of lastCall) {
+        const reply = replies.get(step)?.find((r) => r > seq);
+        if (reply !== undefined)
+            out.push({ seq, step, assistantSeq: reply });
+    }
+    return out.sort((a, b) => a.seq - b.seq);
+}

package/dist/evals/step-replay.d.ts

@@ -0,0 +1,113 @@
+import { type ContentBlock, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
+import type { AgentDefinition, ModelRef } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
+import { type Selection } from "../conversations/selection.js";
+import { type MediaSourceDeps } from "../runtime/model-call.js";
+import type { ProviderRegistry } from "../runtime/providers.js";
+import { type DriftReason } from "./reconstruct.js";
+import type { CaseSnapshot } from "./snapshot.js";
+/**
+ * 单步回放（D2 / C5）：由用例快照还原某一步的模型请求，换成候选（agent 版本 / 模型 / 参数 / 指令）重发，
+ * 与快照里该步的回复（基线）比较。工具定义沿用记录（C5）；媒体按快照的组织与对话取原附件（C3）。
+ * 只读快照，不写任何日志。
+ */
+/** 评测候选：各项都可缺省（缺省 = 沿用用例自己的）。 */
+export interface EvalCandidate {
+    agentVersion?: number;
+    model?: ModelRef;
+    modelParams?: Record<string, ParamValue>;
+    instructions?: string;
+}
+/** 某个用例上的候选（{@link resolveCandidate}）。 */
+export interface ResolvedCandidate {
+    definition: AgentDefinition;
+    agentVersion: number;
+    model: ModelRef;
+    /** 发送前再按候选模型的声明宽松处理（补默认值，见 {@link replayStep}）。 */
+    params: Record<string, ParamValue>;
+    /** 与用例的原版本、原定义完全相同时为 false：此时按基线还原（不改 system / 参数，漂移可比）。 */
+    changed: boolean;
+    /** The run used a person's model switch and the candidate's model replaces it (`model_switched`). */
+    overridesSwitch: boolean;
+    /**
+     * A plugin template's child case: the template's current version (set by the worker), compared
+     * with the logged one for `subagent_changed` when the candidate changed.
+     */
+    subagentTemplate?: {
+        id: string;
+        version: number;
+    };
+    /**
+     * A child case under another agent version: that version's own definition (with the candidate's
+     * instructions), compared with the logged sub-agent for `subagent_changed`. Never rendered.
+     */
+    subagentVersion?: AgentDefinition;
+}
+/** Where a child case's sub-agent came from (`subagent_started.template.source`). */
+export type SubagentSource = "general" | "inline" | "plugin" | "agent";
+/** 候选一次请求的输出。 */
+export interface ReplayOutput {
+    content: ContentBlock[];
+    stopReason: StopReason;
+    usage: ModelUsage;
+    provider: string;
+    model: string;
+    latencyMs: number;
+}
+export interface StepReplayDeps {
+    registry: Pick<ProviderRegistry, "resolve">;
+    config: () => KernelConfig;
+    /** 附件来源（与运行时同一个，按组织 + 对话取）；不给时媒体一律按「不再可用」占位。 */
+    media?: MediaSourceDeps;
+}
+/**
+ * 候选在某个用例上所用的模型（{@link resolveCandidate} 的同一规则）：候选模型，否则候选版本的模型，否则用例原版本的
+ * 模型（`baseModel`）。估算只用存好的 `base_model`，不读快照。
+ * A child case (`subagent` given) keeps its logged model unless the candidate names one; only an
+ * org agent child (`agent`) takes another version's model, as its dispatch would (a template's
+ * tier does not follow the parent's model).
+ */
+export declare function candidateModel(baseModel: ModelRef, c: EvalCandidate, versionDef?: AgentDefinition, switchedModel?: ModelRef, subagent?: SubagentSource): ModelRef;
+/**
+ * 候选落到某个用例上：定义取候选版本的（`versionDef`，由调用方按 `agentVersion` 查好），否则用例自己的版本；
+ * 指令、模型覆盖其上。参数：给了用候选的；没给时模型未变沿用定义的 `modelParams`，换了模型为空（原参数属于原模型）。
+ * `base.definition` is the definition the run used (`caseBase`: the person's switch applied); a
+ * candidate version gets the same switch (`base.selection`) unless the candidate sets a model.
+ */
+export declare function resolveCandidate(base: {
+    definition: AgentDefinition;
+    agentVersion: number;
+    selection?: Selection;
+}, c: EvalCandidate, versionDef?: AgentDefinition, 
+/** A child case: its sub-agent's source (the definition is then always the logged one). */
+subagent?: SubagentSource): ResolvedCandidate;
+/**
+ * 候选请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是这次尝试应计入预算的估算用量，
+ * `cause` 是原始错误（调用方按它分类重试）。请求发出之前的失败（解析模型、取附件）原样抛出，不计费。
+ */
+export declare class ReplayAttemptError extends Error {
+    readonly cause: unknown;
+    readonly tokens: number;
+    constructor(cause: unknown, tokens: number);
+}
+/**
+ * 回放一步：基线取快照里该步的回复与用量；候选请求 = `reconstructRequest`（候选未变时按基线还原，
+ * 否则带候选的定义、版本与参数——参数按候选模型的声明宽松处理，与运行时一致），用 `consumeModelStream` 收完。
+ * 请求发出之前的错误原样抛出（`agent.model_unavailable`、取附件暂时失败为 `MediaUnavailableError`）；请求发出之后的
+ * 错误包成 {@link ReplayAttemptError}（带估算用量，调用方计入预算后按 `cause` 分类重试）。
+ * 模型按部署范围解析（与运行时一致；组织级模型准入若在第二段落地，须同样覆盖评测候选）。
+ * 不另设单次请求的墙钟时限：与运行时一样只有流空闲看门狗（`streamIdleTimeoutMs` / `runtime.streamIdleMs`）。
+ */
+export declare function replayStep(d: StepReplayDeps, s: CaseSnapshot, call: {
+    seq: number;
+    step: number;
+    assistantSeq: number;
+}, candidate: ResolvedCandidate, signal: AbortSignal): Promise<{
+    baseline: {
+        content: ContentBlock[];
+        stopReason: StopReason;
+        usage: ModelUsage | null;
+    };
+    candidate: ReplayOutput;
+    drift: DriftReason[];
+}>;

package/dist/evals/step-replay.js

@@ -0,0 +1,181 @@
+import { sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { effectiveDefinition, NO_SELECTION, sameModel, } from "../conversations/selection.js";
+import { estimateTokens } from "../runtime/context/tokens.js";
+import { consumeModelStream, MediaUnavailableError, } from "../runtime/model-call.js";
+import { loadSnapshotMedia, reconstructRequest } from "./reconstruct.js";
+/** 键排序后的 JSON（比较参数是否相同）。 */
+const canonical = (v) => JSON.stringify(Object.keys(v)
+    .sort()
+    .map((k) => [k, v[k]]));
+/**
+ * 候选在某个用例上所用的模型（{@link resolveCandidate} 的同一规则）：候选模型，否则候选版本的模型，否则用例原版本的
+ * 模型（`baseModel`）。估算只用存好的 `base_model`，不读快照。
+ * A child case (`subagent` given) keeps its logged model unless the candidate names one; only an
+ * org agent child (`agent`) takes another version's model, as its dispatch would (a template's
+ * tier does not follow the parent's model).
+ */
+export function candidateModel(baseModel, c, versionDef, switchedModel, subagent) {
+    if (c.model !== undefined)
+        return c.model;
+    if (subagent !== undefined && subagent !== "agent")
+        return baseModel;
+    // a candidate version keeps the person's switch, as resolveCandidate replays it (a child case
+    // has no switch: its model is the logged one)
+    if (c.agentVersion !== undefined && versionDef !== undefined) {
+        return switchedModel ?? versionDef.model;
+    }
+    return baseModel;
+}
+/**
+ * 候选落到某个用例上：定义取候选版本的（`versionDef`，由调用方按 `agentVersion` 查好），否则用例自己的版本；
+ * 指令、模型覆盖其上。参数：给了用候选的；没给时模型未变沿用定义的 `modelParams`，换了模型为空（原参数属于原模型）。
+ * `base.definition` is the definition the run used (`caseBase`: the person's switch applied); a
+ * candidate version gets the same switch (`base.selection`) unless the candidate sets a model.
+ */
+export function resolveCandidate(base, c, versionDef, 
+/** A child case: its sub-agent's source (the definition is then always the logged one). */
+subagent) {
+    const selection = base.selection ?? NO_SELECTION;
+    const agentVersion = c.agentVersion ?? base.agentVersion;
+    // a child case renders its logged effective definition; another version is only compared
+    const from = subagent === undefined && c.agentVersion !== undefined && versionDef !== undefined
+        ? effectiveDefinition(versionDef, selection)
+        : base.definition;
+    const model = candidateModel(base.definition.model, c, versionDef, selection.model ?? undefined, subagent);
+    // an org agent child under another version runs that version's params, as its dispatch would,
+    // even when the model stayed the same
+    const orgAgentVersion = subagent === "agent" && c.agentVersion !== undefined && versionDef !== undefined
+        ? versionDef
+        : undefined;
+    const params = c.modelParams ??
+        (orgAgentVersion !== undefined && sameModel(model, orgAgentVersion.model)
+            ? { ...(orgAgentVersion.modelParams ?? {}) }
+            : sameModel(model, from.model)
+                ? { ...(from.modelParams ?? {}) }
+                : {});
+    const definition = {
+        ...from,
+        model,
+        modelParams: params,
+        ...(c.instructions !== undefined && { instructions: c.instructions }),
+    };
+    const changed = agentVersion !== base.agentVersion ||
+        !sameModel(model, base.definition.model) ||
+        definition.instructions !== base.definition.instructions ||
+        canonical(params) !== canonical(base.definition.modelParams ?? {});
+    const overridesSwitch = selection.model !== null && !sameModel(model, selection.model);
+    const otherVersion = subagent !== undefined && agentVersion !== base.agentVersion && versionDef !== undefined;
+    return {
+        definition,
+        agentVersion,
+        model,
+        params,
+        changed,
+        overridesSwitch,
+        ...(otherVersion && {
+            subagentVersion: {
+                ...versionDef,
+                ...(c.instructions !== undefined && { instructions: c.instructions }),
+            },
+        }),
+    };
+}
+/**
+ * 候选请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是这次尝试应计入预算的估算用量，
+ * `cause` 是原始错误（调用方按它分类重试）。请求发出之前的失败（解析模型、取附件）原样抛出，不计费。
+ */
+export class ReplayAttemptError extends Error {
+    cause;
+    tokens;
+    constructor(cause, tokens) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.cause = cause;
+        this.tokens = tokens;
+        this.name = "ReplayAttemptError";
+    }
+}
+/** 快照里该步的回复（`assistantSeq`）与其后同一步的第一条 usage。 */
+function baselineOf(s, call) {
+    const reply = s.events.find((e) => e.seq === call.assistantSeq);
+    const p = (reply?.payload ?? { content: [], stopReason: "end_turn" });
+    const usage = s.events.find((e) => e.type === "usage" &&
+        e.payload.purpose === undefined &&
+        e.runId === s.runId &&
+        e.seq > call.seq &&
+        e.payload.step === call.step);
+    let u = null;
+    if (usage) {
+        const x = usage.payload;
+        u = {
+            inputTokens: x.inputTokens,
+            outputTokens: x.outputTokens,
+            cacheReadTokens: x.cacheReadTokens,
+            cacheWriteTokens: x.cacheWriteTokens,
+        };
+    }
+    return { content: p.content, stopReason: p.stopReason, usage: u };
+}
+/**
+ * 回放一步：基线取快照里该步的回复与用量；候选请求 = `reconstructRequest`（候选未变时按基线还原，
+ * 否则带候选的定义、版本与参数——参数按候选模型的声明宽松处理，与运行时一致），用 `consumeModelStream` 收完。
+ * 请求发出之前的错误原样抛出（`agent.model_unavailable`、取附件暂时失败为 `MediaUnavailableError`）；请求发出之后的
+ * 错误包成 {@link ReplayAttemptError}（带估算用量，调用方计入预算后按 `cause` 分类重试）。
+ * 模型按部署范围解析（与运行时一致；组织级模型准入若在第二段落地，须同样覆盖评测候选）。
+ * 不另设单次请求的墙钟时限：与运行时一样只有流空闲看门狗（`streamIdleTimeoutMs` / `runtime.streamIdleMs`）。
+ */
+export async function replayStep(d, s, call, candidate, signal) {
+    const baseline = baselineOf(s, call);
+    const { provider, info } = await d.registry.resolve(candidate.model);
+    let media;
+    if (d.media) {
+        try {
+            media = await loadSnapshotMedia(s, call.seq, info, d.media);
+        }
+        catch (err) {
+            throw new MediaUnavailableError(err);
+        }
+    }
+    const { request, drift, mediaTokens } = reconstructRequest(s, call.seq, {
+        model: info,
+        ...(candidate.changed && {
+            definition: candidate.definition,
+            agentVersion: candidate.agentVersion,
+            params: sanitizeParams(info.parameters, candidate.params).value,
+            modelRef: candidate.model,
+            ...(candidate.subagentTemplate !== undefined && {
+                subagentTemplate: candidate.subagentTemplate,
+            }),
+            ...(candidate.subagentVersion !== undefined && {
+                subagentVersion: candidate.subagentVersion,
+            }),
+        }),
+        ...(media !== undefined && { mediaInfo: media.mediaInfo, media: media.media }),
+    });
+    const idleMs = info.streamIdleTimeoutMs ?? d.config().runtime.streamIdleMs;
+    const started = Date.now();
+    let streamedChars = 0;
+    let out;
+    try {
+        out = await consumeModelStream(provider, request, idleMs, signal, (ev) => {
+            streamedChars += ev.text.length;
+        });
+    }
+    catch (err) {
+        // 请求已发出：供应商流里不带中途用量（model-provider@2 只在 message_complete 给 usage），
+        // 按估算计费——输入 = 与运行时同一个估算器，输出 = 已流出的字符数 / 4
+        const input = estimateTokens(request.messages, request.system, request.tools, mediaTokens);
+        throw new ReplayAttemptError(err, input + Math.ceil(streamedChars / 4));
+    }
+    return {
+        baseline,
+        candidate: {
+            content: out.content,
+            stopReason: out.stopReason,
+            usage: out.usage,
+            provider: candidate.model.provider,
+            model: candidate.model.model,
+            latencyMs: Date.now() - started,
+        },
+        drift,
+    };
+}

package/dist/evals/trajectory.controller.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type TrajectoryDetail, type TrajectoryListItem, type TrajectoryService } from "./trajectory.service.js";
+declare const ListQuery: z.ZodObject<{
+    agentId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        chat: "chat";
+        eval: "eval";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        aborted: "aborted";
+        completed: "completed";
+        failed: "failed";
+        queued: "queued";
+        running: "running";
+        waiting: "waiting";
+    }>>;
+    before: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** 详情的运行窗口：`runId` 与 `before` / `limit` 互斥；都不给时读全对话（形状不变）。 */
+declare const DetailQuery: z.ZodObject<{
+    runId: z.ZodOptional<z.ZodString>;
+    before: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * 轨迹查看器（`/api/v1/orgs/:orgId/trajectories`）：`trajectories.read`（member 起、只给人），
+ * 服务里再判定「组织管理员或 agent 负责人」；无权一律 404 `trajectory.not_found`。
+ */
+export declare class TrajectoryController {
+    private readonly trajectories;
+    constructor(trajectories: TrajectoryService);
+    list(principal: Principal, org: OrgContext, q: z.infer<typeof ListQuery>): Promise<{
+        items: TrajectoryListItem[];
+        next: string | null;
+    }>;
+    get(principal: Principal, org: OrgContext, conversationId: string, q: z.infer<typeof DetailQuery>): Promise<TrajectoryDetail>;
+}
+export {};

package/dist/evals/trajectory.controller.js

@@ -0,0 +1,88 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Inject, Param, Query } from "@nestjs/common";
+import { z } from "zod";
+import { TRAJECTORIES } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { RUN_STATUSES, } from "./trajectory.service.js";
+const ListQuery = z.object({
+    agentId: z.string().min(1).max(100).optional(),
+    kind: z.enum(["chat", "eval"]).optional(),
+    status: z.enum(RUN_STATUSES).optional(),
+    before: z.string().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+/** 详情的运行窗口：`runId` 与 `before` / `limit` 互斥；都不给时读全对话（形状不变）。 */
+const DetailQuery = z
+    .object({
+    runId: z.string().min(1).max(100).optional(),
+    before: z.string().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(50).optional(),
+})
+    .refine((q) => q.runId === undefined || (q.before === undefined && q.limit === undefined), {
+    message: "runId cannot be combined with before or limit",
+    path: ["runId"],
+});
+/** 只给 `before` 时的页大小。 */
+const DEFAULT_RUN_PAGE = 20;
+/**
+ * 轨迹查看器（`/api/v1/orgs/:orgId/trajectories`）：`trajectories.read`（member 起、只给人），
+ * 服务里再判定「组织管理员或 agent 负责人」；无权一律 404 `trajectory.not_found`。
+ */
+let TrajectoryController = class TrajectoryController {
+    trajectories;
+    constructor(trajectories) {
+        this.trajectories = trajectories;
+    }
+    async list(principal, org, q) {
+        const user = requireUser(principal);
+        return this.trajectories.list(org.orgId, user.account.id, {
+            limit: q.limit,
+            ...(q.agentId !== undefined && { agentId: q.agentId }),
+            ...(q.kind !== undefined && { kind: q.kind }),
+            ...(q.status !== undefined && { status: q.status }),
+            ...(q.before !== undefined && { before: q.before }),
+        });
+    }
+    async get(principal, org, conversationId, q) {
+        const user = requireUser(principal);
+        const window = q.runId !== undefined
+            ? { runId: q.runId }
+            : q.limit !== undefined || q.before !== undefined
+                ? {
+                    limit: q.limit ?? DEFAULT_RUN_PAGE,
+                    ...(q.before !== undefined && { before: q.before }),
+                }
+                : undefined;
+        return this.trajectories.get(org.orgId, user.account.id, conversationId, patTokenId(user), window);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("trajectories.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Query(new ZodPipe(ListQuery)))
+], TrajectoryController.prototype, "list", null);
+__decorate([
+    Get(":conversationId"),
+    OrgAction("trajectories.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("conversationId")),
+    __param(3, Query(new ZodPipe(DetailQuery)))
+], TrajectoryController.prototype, "get", null);
+TrajectoryController = __decorate([
+    Controller("api/v1/orgs/:orgId/trajectories"),
+    __param(0, Inject(TRAJECTORIES))
+], TrajectoryController);
+export { TrajectoryController };