@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/subagent/subagent-registry.js

@@ -0,0 +1,167 @@
+import { DESC_LIMIT } from './roster-block.js';
+/**
+ * 内置子 Agent 注册表：宿主显式 `register`（以前靠 Nest 装饰器 + DiscoveryService 扫）。
+ * 名字重复、旧名冲突、说明过长、两个互斥标记同标都在注册期抛。
+ *
+ * 花名册顺序 = 注册顺序。
+ */
+export class SubagentRegistry {
+    options;
+    byName = new Map();
+    /** 旧名 → 现名。 */
+    aliases = new Map();
+    labelMax;
+    constructor(options = {}) {
+        this.options = options;
+        this.labelMax = options.labelMax ?? 20;
+    }
+    register(meta, provider) {
+        const { name } = meta;
+        if (this.byName.has(name) || this.aliases.has(name)) {
+            throw new Error(`duplicate subagent name '${name}'`);
+        }
+        // 花名册每行只显示前 DESC_LIMIT 个码点。说明是我们写的，写长了就是一段没人看得见
+        // 的交代——逼着把「何时派、交回什么」写进前 60 字。
+        if (Array.from(meta.description.trim()).length > DESC_LIMIT) {
+            throw new Error(`subagent '${name}' description exceeds ${DESC_LIMIT} code points (the roster cuts the rest)`);
+        }
+        const labelLength = Array.from(meta.label.trim()).length;
+        if (labelLength === 0 || labelLength > this.labelMax) {
+            throw new Error(`subagent '${name}' label must be 1..${this.labelMax} code points`);
+        }
+        if (meta.permission && meta.optIn) {
+            throw new Error(`subagent '${name}' declares both permission and optIn`);
+        }
+        for (const former of meta.formerNames ?? []) {
+            if (former === name || this.byName.has(former)) {
+                throw new Error(`subagent former name '${former}' is also a current name`);
+            }
+            if (this.aliases.has(former)) {
+                throw new Error(`subagent former name '${former}' is claimed twice`);
+            }
+        }
+        this.options.validate?.(meta);
+        for (const former of meta.formerNames ?? []) {
+            this.aliases.set(former, name);
+        }
+        this.byName.set(name, provider ? { meta, provider } : { meta });
+    }
+    /** 现名（认旧名）；没登记过返回 null。不看可用性。 */
+    currentName(name) {
+        if (this.byName.has(name))
+            return name;
+        return this.aliases.get(name) ?? null;
+    }
+    /** 这个名字（含旧名）的定义；没有或此刻不可用返回 null。 */
+    get(name) {
+        const current = this.currentName(name);
+        if (current === null)
+            return null;
+        const entry = this.byName.get(current);
+        return entry && this.available(entry) ? entry.meta : null;
+    }
+    /** 此刻可用的全部定义（注册顺序）。 */
+    list() {
+        return [...this.byName.values()]
+            .filter(e => this.available(e))
+            .map(e => e.meta);
+    }
+    /** 注册过的全部定义（含此刻不可用的），带可用性。后台页用。 */
+    listAll() {
+        return [...this.byName.values()].map(e => ({
+            meta: e.meta,
+            available: this.available(e),
+        }));
+    }
+    /**
+     * 注册过的全部现名，**不看可用性**。给「名字不许与内置子 Agent 撞」这类静态判断用：
+     * 按 `list()` 判的话，取数员不可用时别人就能占走它的名字，可用之后两者同名。
+     */
+    allNames() {
+        return [...this.byName.keys()];
+    }
+    /** 名字 → 界面默认叫法，**含旧名**；不看可用性（历史里派过的照样要叫得出来）。 */
+    defaultLabels() {
+        const out = {};
+        for (const { meta } of this.byName.values())
+            out[meta.name] = meta.label;
+        for (const [former, current] of this.aliases) {
+            const entry = this.byName.get(current);
+            if (entry)
+                out[former] = entry.meta.label;
+        }
+        return out;
+    }
+    /**
+     * 这个名字是不是叶子（不给 `Delegate`、花名册清空）：`leaf` / `functional` /
+     * 宿主的 `impliesLeaf`。没登记过的名字（宿主自己的子 Agent）返回 false。
+     */
+    isLeaf(name) {
+        const meta = this.get(name);
+        if (!meta)
+            return false;
+        return (meta.leaf === true ||
+            meta.functional === true ||
+            (this.options.impliesLeaf?.(meta) ?? false));
+    }
+    /** 这个名字要的权限点；不要或没登记过返回 null。 */
+    requiredPermission(name) {
+        return this.get(name)?.permission ?? null;
+    }
+    /**
+     * 判据输入下这个定义派不派得出（花名册与派生同一句）：要权限点的要发起人有且父允许；
+     * 点名挂载的要父点了名。
+     */
+    permits(meta, access) {
+        if (meta.permission &&
+            !(access.allowPermissioned && access.permissions.has(meta.permission))) {
+            return false;
+        }
+        if (meta.optIn && !(access.optIn ?? []).includes(meta.name))
+            return false;
+        return true;
+    }
+    /**
+     * 花名册：此刻可用、对这份判据输入派得出的定义。`filter` 是宿主的附加条件
+     * （agent-base：顶替型只在当前模型缺那项能力且父配了顶替模型时列）——**不广告一个
+     * 派不出来的东西**，派生那一侧（`SpawnPolicy.checkSpawn`）要用同一个判据。
+     */
+    roster(access, filter) {
+        return this.list()
+            .filter(m => this.permits(m, access) && (filter?.(m) ?? true))
+            .map(m => ({ name: m.name, description: m.description }));
+    }
+    /**
+     * 这个子 Agent 本轮要摘掉的恒上桌工具：声明了 `systemTools` 时，`alwaysOn` 那几组里
+     * 名单外的全部。没声明返回空数组（与父一样）。
+     */
+    excludedSystemTools(name, tools, alwaysOnCategories = ['system']) {
+        const allow = this.get(name)?.systemTools;
+        if (!allow)
+            return [];
+        return tools
+            .listMeta()
+            .filter(m => alwaysOnCategories.includes(m.category) && !allow.includes(m.name))
+            .map(m => m.name);
+    }
+    available(entry) {
+        return entry.provider?.isAvailable?.() ?? true;
+    }
+}
+/**
+ * 通用子 Agent 的固定人格提示词。**短得几乎没有内容，这是对的**：处境说明（看不到
+ * 调用方历史、产出原样回投、卡住可以交回去问）归平台，由 `buildSubagentSituationBlock`
+ * 对每个子会话注入；剩下这一句才是「通用款」独有的——它没有领域设定。
+ */
+export const GENERAL_PURPOSE_PROMPT = '你没有特定的领域设定，也没有预设的工作套路。按任务描述本身的要求来做：它要什么就产出什么，需要什么手段就用什么手段。';
+/**
+ * 内置「通用子 Agent」。**除人格外一个字段都不设，是它的全部要点**：工具、步数（以及
+ * 宿主的档位、推理等级）统统由派生它的那个父决定。宿主要用就 `registry.register(GENERAL_PURPOSE_SUBAGENT)`。
+ */
+export const GENERAL_PURPOSE_SUBAGENT = {
+    name: 'general-purpose',
+    label: '通用 Agent',
+    description: '通用子 Agent：无特定领域设定，适合把一段自包含的任务整个交出去',
+    prompt: GENERAL_PURPOSE_PROMPT,
+};
+//# sourceMappingURL=subagent-registry.js.map

package/dist/subagent/subagent-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-registry.js","sourceRoot":"","sources":["../../src/subagent/subagent-registry.ts"],"names":[],"mappings":"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"}

package/dist/subagent/subagent-sessions.d.ts

@@ -0,0 +1,213 @@
+import type { MessageHub } from '../loop/message-hub.js';
+import type { SubagentAwaitLease, TreeBudget, WakeChannel } from '../ports/coordination.js';
+import { type LoggerFactory } from '../ports/logger.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { SessionRecord, SessionStore } from '../ports/session-store.js';
+import type { ToolAgentContext } from '../tools/agent-tool.interface.js';
+/** 兜底扫描的缺省「空闲多久才算嫌疑」。 */
+export declare const SUBAGENT_SWEEP_IDLE_MS = 60000;
+/** 派一个新的子 Agent 的请求（`Delegate` 从 `ToolContext` 拼出来）。 */
+export interface SpawnRequest {
+    agentName: string;
+    /** 一句话任务标题（模型显式给，界面展示）。 */
+    title: string;
+    prompt: string;
+    /** 派它的会话（父）。 */
+    parentSessionId: string;
+    rootSessionId: string;
+    /** 父这一轮的跑次 id——子会话的 `parentRunId`，父会话经它找到。 */
+    parentRunId: string;
+    /** 父这一轮的深度。 */
+    depth: number;
+    userId: string | null;
+    /** 父这一轮跑的 agent（宿主的扩展字段：跑哪个、哪一版……）与模型能力。 */
+    agent: ToolAgentContext;
+    /** 父会话的附加信息；缺省照抄给子会话。 */
+    sessionMetadata: Readonly<Record<string, unknown>>;
+    /** 发起人此刻的权限点。缺省空（fail-closed）。 */
+    initiatorPermissions: ReadonlySet<string>;
+}
+/**
+ * 派不派得出（宿主回答）。
+ *
+ * - `unknown`：没有这个子 Agent（或此刻不可用）。`Delegate` 的报错让模型去核对花名册。
+ * - `refused`：有，但这一次不行——`message` 原样给模型，要说清「谁、为什么」不够格，
+ *   否则模型会换个名字再试（agent-base：权限点不够、「你自己就能看图，别派识图员」）。
+ * - `ok`：可以。`attrs` / `metadata` 写进子会话行（缺省：attrs 空、metadata 照抄父的）。
+ */
+export type SpawnCheck = {
+    ok: true;
+    attrs?: Readonly<Record<string, unknown>>;
+    metadata?: Readonly<Record<string, unknown>>;
+} | {
+    ok: false;
+    reason: 'unknown';
+} | {
+    ok: false;
+    reason: 'refused';
+    message: string;
+};
+/**
+ * 宿主的派生策略。花名册与这里**必须是同一个判据**（花名册不列只是不广告，模型凭名字
+ * 照样派得动）——用 `SubagentRegistry` 的话，`registrySpawnPolicy` 就是现成的一份。
+ */
+export interface SpawnPolicy {
+    checkSpawn(req: SpawnRequest): Promise<SpawnCheck>;
+    /**
+     * 子会话建好、任务投递**之前**：宿主为子会话定下它要用的东西（agent-base 分身：
+     * 派活快照）。子会话此刻还没有任务、不会被唤醒，第一轮就能读到。抛错 = 这次派生
+     * 失败（名额归还，错误上抛）。
+     *
+     * `notes` 拼在回执最前面（「技能《×××》已停用，未带」）；**为空就别给**，回执逐字不变。
+     */
+    onSubagentCreated?(req: SpawnRequest & {
+        childSessionId: string;
+    }): Promise<{
+        notes?: string[];
+    }>;
+}
+export type SpawnOutcome = {
+    ok: true;
+    childSessionId: string;
+    notes?: string[];
+} | {
+    ok: false;
+    reason: 'unknown' | 'tree_full';
+} | {
+    ok: false;
+    reason: 'refused';
+    message: string;
+};
+/**
+ * 追加任务的目标校验结果。`cursorBefore` 是发起追加**之前**的里程碑游标：同步等待据它
+ * 判「这一轮跑完了没有」，取产出也只取它之后的。首次 idle 之前追加时为 null，语义退化
+ * 成「等首次 settle」。
+ */
+export type FollowUpTarget = {
+    ok: true;
+    cursorBefore: number | null;
+} | {
+    ok: false;
+    reason: 'not_found' | 'not_own_child';
+};
+/** 子会话一轮的回执（同步返回与回投 inbox 同源）。 */
+export interface SubagentResult {
+    body: string;
+    status: string;
+    /** 只有失败才带（正常收尾的 `stop` 写进「原因」是误导）。 */
+    stopReason: string | null;
+}
+/** loop 设置一个 tick 时要的子会话信息。 */
+export interface SubagentTickInfo {
+    kind: SessionRecord['kind'];
+    /** 子会话 = 父跑次深度 + 1；根会话 0。 */
+    depth: number;
+    parentRunId: string | null;
+    /** 子 Agent 名（钉在会话上的那个，可能是旧名）；根会话 null。 */
+    agentName: string | null;
+    title: string | null;
+}
+export interface SubagentSessionsDeps {
+    sessions: SessionStore;
+    /** 消息中心：投递（`post`）与读消息（`store`）。 */
+    hub: MessageHub;
+    wake: WakeChannel;
+    runs: RunStore;
+    awaitLease: SubagentAwaitLease;
+    treeBudget: TreeBudget;
+    policy: SpawnPolicy;
+    /** 每棵树同时存活的子 Agent 上限，缺省 `MAX_LIVE_SUBS_PER_TREE`。 */
+    maxLivePerTree?: number;
+    /** 兜底扫描的空闲门槛，缺省 `SUBAGENT_SWEEP_IDLE_MS`。 */
+    sweepIdleMs?: number;
+    logger?: LoggerFactory;
+}
+/**
+ * 子会话的生命周期：派生（受理段，**不 await 子跑完**）、追加任务、取回执、收尾回投、
+ * 兜底扫描。搬自 agent-base `SubagentSessionService`，会话行走 `SessionStore`、消息走
+ * `MessageHub`，派生判据交给宿主的 `SpawnPolicy`。
+ *
+ * 子会话此后由 loop 独立驱动（inbox + 唤醒），**同步与异步是同一条实现**：子会话都是
+ * 独立持久跑的，区别只在父等不等它（`Delegate`）。
+ *
+ * 宿主要接两处：`LoopHost.afterTick` 里调 `finalizeIfIdle`，启动时调一次 `sweepStale`。
+ */
+export declare class SubagentSessions {
+    private readonly deps;
+    private readonly logger;
+    readonly maxLivePerTree: number;
+    constructor(deps: SubagentSessionsDeps);
+    /** 新建：问宿主 → 占名额 → 建会话 → 宿主补料 → 投任务 → 唤醒，即返 handle。 */
+    spawn(req: SpawnRequest): Promise<SpawnOutcome>;
+    /**
+     * 追加任务前的目标校验——**必须先于投递**，且与投递分两步：同步等待的租约要夹在
+     * 「校验通过」与「投递」之间（见 `Delegate` 的追加任务那段）。
+     *
+     * 归属判据是「**直接子**」（子的 `parentRunId` 所属会话 == 当前会话），不是「同一棵
+     * 树」：孙辈的 handle 本就不会出现在父的上下文里，能续到孙只可能是编了个 id 或从子的
+     * 产出正文里抄了一个。
+     */
+    resolveFollowUpTarget(input: {
+        childSessionId: string;
+        parentSessionId: string;
+    }): Promise<FollowUpTarget>;
+    /**
+     * 把追加任务投进子会话并唤醒它。与派生尾段**逐字相同**的通道，子那边零特判——「子
+     * 记得自己写过什么」不是这里做的，是会话本身没被丢弃。子此刻仍在跑就是软插话。
+     *
+     * **不占名额**：名额记的是「同时有几个**新派生**的子」，与「存活 = 游标为 null」同一个口径。
+     */
+    deliverFollowUp(input: {
+        childSessionId: string;
+        prompt: string;
+        userId: string | null;
+    }): Promise<void>;
+    /**
+     * 子已到达 idle 终态后，取它自 `since` 以来的回执。**与收尾回投 inbox 的那份同源**
+     * （同一个取数 + 同一套中和）——换个 `run_in_background` 值就换一份结论，是没法排查
+     * 的那类 bug。追加任务传发起前的游标，否则父会连同上一轮全文再收一遍。
+     */
+    buildResult(childSessionId: string, since?: number | null): Promise<SubagentResult>;
+    /**
+     * 里程碑游标是否已越过 `cursor`（＝子在这次等待期间到达过一次 idle 终态）。null 即
+     * 「首次 settle 了没有」。**追加任务不能沿用「非 null 即完成」**——那个条件在追加发起的
+     * 一瞬间就成立（上一轮推进过），父会立刻拿着上一轮的结果返回。
+     */
+    hasAdvancedPast(childSessionId: string, cursor: number | null): Promise<boolean>;
+    /** loop 设置 tick 时要的子会话信息（深度、钉住的子 Agent 名……）。会话不存在返回 null。 */
+    tickInfo(sessionId: string): Promise<SubagentTickInfo | null>;
+    /**
+     * 子会话空转终态 → 把新产出中和后作为里程碑回投父 inbox 并唤醒父。
+     *
+     * loop 在每个 tick 收尾（锁已释放、re-wake 之前）对每个会话**无条件**调（`LoopHost.afterTick`），
+     * 这里自查：非子会话直接返回。
+     *
+     * **只还一次名额**：「存活」= 从派生到首次 idle 终态，判据是游标为 null。被追加任务
+     * 续跑后再次 idle 只回投新产出、不再还。
+     *
+     * **并发安全**：两次抢锁成功的唤醒可能并发进来、读到同一个旧游标。所有副作用都收在一次
+     * 乐观 CAS（`SessionStore.advanceMilestone`）之后：先按**旧**游标取产出，再把游标推进到
+     * 产出的最大 seq（无产出从序列取号）；只有 CAS 成功的那一个回投 + 唤醒 + 还名额。
+     *
+     * 全程不抛：失败只记日志，兜底扫描是后备。
+     */
+    finalizeIfIdle(childSessionId: string): Promise<void>;
+    /**
+     * 兜底：子 loop 可能在回投 / 还名额之前崩掉或丢锁。对每个嫌疑重跑一次收尾（幂等），
+     * 再把每棵被碰过的树的名额覆盖为真值。**先收尾后校正**：收尾会把游标从 null 推成非
+     * null，校正读到的才是收尾之后的存活数。宿主在启动时调一次（fire-and-forget）。
+     */
+    sweepStale(): Promise<void>;
+    private deliver;
+    /**
+     * 子会话自 `since` 以来的 assistant 产出与终态。游标是消息 `seq`（会话内单调）——
+     * **不是时间戳**：挂钟会回拨，回拨之后新产出会被判成「旧的」直接跳过，父收到的回执
+     * 格式完好、内容缺一段。
+     *
+     * `watermark` = 取到的行里最大的 seq；没取到行时为 null（调用方从序列取号）。游标取自
+     * **取到的那些行**而不是独立取一个「当下」——后者可能跨到尚未取到的消息之后。
+     */
+    private collectOutput;
+    private resultOf;
+}
+//# sourceMappingURL=subagent-sessions.d.ts.map

package/dist/subagent/subagent-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-sessions.d.ts","sourceRoot":"","sources":["../../src/subagent/subagent-sessions.ts"],"names":[],"mappings":"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"}