qlogicagent 2.19.13 → 2.20.1

package/dist/types/orchestration/solo-evaluator.d.ts

@@ -11,7 +11,7 @@
  *   6. solo.select → merge winning worktree, clean up others
  *
  * Key design:
- *   - Solo = special project type (persisted in .qlogicagent/solos/)
+ *   - Solo = special project type persisted by the Gateway RunState authority
  *   - Agents share the same initial config but operate in isolated worktrees
  *   - User controls the evaluation timing (not automatic)
  *   - Follow-up instructions to individual agents supported
@@ -20,30 +20,28 @@
  */
 import type { DelegateBridge } from "./delegate-bridge.js";
 import type { SoloState, SoloAgentState, SoloEvaluation, SoloStatus, SoloStartParams, SoloSelectParams, SoloSpec } from "../protocol/wire/acp-agent-management.js";
-export declare function deriveSoloDelegateProjectId(registeredProjectRoot: string): string;
 export interface SoloCallbacks {
     log?: {
         info(msg: string): void;
         warn(msg: string): void;
         debug?(msg: string): void;
     };
-    onProgress?: (soloId: string, agentId: string, state: SoloAgentState, progress?: string, worktreePath?: string) => void;
-    onEvaluation?: (soloId: string, evaluation: SoloEvaluation) => void | Promise<void>;
+    onProgress?: (soloId: string, agentId: string, state: SoloAgentState, progress: string | undefined, worktreePath: string | undefined, projectId: string) => void;
+    onEvaluation?: (soloId: string, evaluation: SoloEvaluation, projectId: string) => void | Promise<void>;
     /** Streaming text delta from a competing agent (forwarded from child process). */
     onAgentDelta?: (soloId: string, agentId: string, text: string) => void;
-    /** Live tool-activity heartbeat(delegate 路径由 sink.onToolCall 单发;旧路径经共享 PM 的
-     *  turn.tool_call 在 solo-handler 转 solo.agentActivity,PM 在 delegate 路径看不见竞速者)。 */
+    /** Live tool-activity heartbeat emitted from the supervised delegate event sink. */
     onAgentActivity?: (soloId: string, agentId: string, toolName: string) => void;
     /** Token usage report after agent completes. */
     onAgentUsage?: (soloId: string, agentId: string, inputTokens: number, outputTokens: number) => void;
-    /** 激活层(S3c §1.5):gateway-routed delegate 桥(gate 关/未挂 = undefined → 旧本地 spawn 路径)。 */
+    /** Required Gateway delegate access; Solo fails loud when the Host rail is unavailable. */
     getDelegateBridge?: () => DelegateBridge | undefined;
     /**
      * Race reached a terminal state WITHOUT an evaluation winner (all agents failed, or cancelled).
      * The success path uses onEvaluation; this lets the host write back the plan project's planStatus
      * (failed/cancelled) so 历史方案 is correct and recovery doesn't restore a dead run.
      */
-    onTerminal?: (soloId: string, state: SoloState) => void | Promise<void>;
+    onTerminal?: (soloId: string, state: SoloState, projectId: string) => void | Promise<void>;
 }
 /**
  * Solo is an explicit user-launched coding race and every racer is confined to its own disposable
@@ -75,13 +73,11 @@ export declare function buildEvaluationPrompt(originalTask: string, spec: SoloSp
 export declare class SoloEvaluator {
     private callbacks;
     private sessions;
+    private persistenceTails;
     constructor(callbacks?: SoloCallbacks);
-    /** Persist current session data to disk (fire-and-forget). */
-    private persistSession;
-    /** Restore sessions from disk (call once at startup). */
-    restoreFromDisk(cwd?: string): Promise<number>;
-    /** Delete a solo session from memory and disk. */
-    deleteSolo(soloId: string): Promise<boolean>;
+    private snapshotSession;
+    private queuePersistSession;
+    private publishNotification;
     /**
      * Start a Solo Mode PK session.
      * Creates worktrees, spawns agents in parallel, waits for completion, then evaluates.
@@ -131,8 +127,6 @@ export declare class SoloEvaluator {
      * Select a winner and merge their worktree into the main branch.
      */
     select(params: SoloSelectParams): Promise<string>;
-    /** List all solo sessions. */
-    listSessions(): SoloStatus[];
     /** Delete a solo session, killing agents and cleaning up worktrees if still active. */
     delete(soloId: string): Promise<void>;
     /**

package/dist/types/orchestration/solo-persistence.d.ts

@@ -1,19 +1,21 @@
 /**
  * Solo persistence facade over the Gateway-owned RunStateStore.
  */
-import type { PathService } from "../runtime/ports/index.js";
-import type { SoloState, SoloAgentState, SoloEvaluation, SoloSpec } from "../protocol/wire/acp-agent-management.js";
+import type { SoloAgentState, SoloEvaluation, SoloSpec, SoloState } from "../protocol/wire/acp-agent-management.js";
+import { type HostRunStateAuthority } from "./run-state-host-authority.js";
 export interface PersistedSoloState {
     soloId: string;
+    projectId: string;
     state: SoloState;
     task: string;
     cwd: string;
     gitRoot: string;
     agents: Array<{
         agentId: string;
+        displayId?: string;
         memberId: string;
-        /** Handle seq(delegate 路径 MemberHandle 第四元);旧持久化文件缺省时按数组序回填。 */
-        seq?: number;
+        /** Stable delegate handle sequence that distinguishes duplicate agent IDs. */
+        seq: number;
         worktreePath: string;
         worktreeBranch: string;
         state: SoloAgentState;
@@ -35,13 +37,11 @@ export interface PersistedSoloState {
     createdAt: number;
 }
 export interface SoloPersistenceOptions {
-    pathService?: PathService;
+    authority?: HostRunStateAuthority;
 }
 /** Save the latest Solo snapshot through Gateway authority. */
-export declare function saveSoloState(state: PersistedSoloState, cwd?: string, options?: SoloPersistenceOptions): Promise<void>;
+export declare function saveSoloState(state: PersistedSoloState, options?: SoloPersistenceOptions): Promise<void>;
 /** Load the latest Solo snapshot from Gateway authority. */
-export declare function loadSoloState(soloId: string, cwd?: string, options?: SoloPersistenceOptions): Promise<PersistedSoloState | undefined>;
-/** List all solo session IDs with their persisted state. */
-export declare function listSoloSessions(cwd?: string, options?: SoloPersistenceOptions): Promise<PersistedSoloState[]>;
+export declare function loadSoloState(soloId: string, options?: SoloPersistenceOptions): Promise<PersistedSoloState | undefined>;
 /** Delete a Solo run through Gateway authority. */
-export declare function deleteSoloState(soloId: string, cwd?: string, options?: SoloPersistenceOptions): Promise<boolean>;
+export declare function deleteSoloState(soloId: string, options?: SoloPersistenceOptions): Promise<boolean>;

package/dist/types/orchestration/workflow/budget-permission-gate.d.ts

@@ -26,7 +26,7 @@ import { WorkflowPauseSignal, type ExecutionGate } from "./workflow-runtime.js";
 /** The trigger kinds that can start a run. Single source of the union (consumed by the controller). */
 export type WorkflowTriggerKind = "manual" | "schedule" | "im-message" | "webhook" | "intent" | "form";
 /**
- * Node kinds that reach the outside world (network calls, channel sends, agent/tool/mcp side
+ * Node kinds that reach the outside world (network calls, channel sends, Agent/Action side
  * effects). These require explicit authorization to run unattended. Control / data-shaping kinds
  * (set / if / loop / merge / passthrough / trigger) are NOT here — they cannot escape the engine.
  */

package/dist/types/orchestration/workflow/capability-catalog.d.ts

@@ -1,48 +1,25 @@
 /**
- * Capability Catalog (spec D24) — THE single source of truth for "what can a workflow node
- * actually reference". One catalog feeds five consumers: the AI graph builder's prompt +
- * list_capabilities tool, the canvas "+" suggestions, the advanced node library, the node
- * config dropdowns, and Hub bundle `requires` verification.
- *
- * Channels are deliberately ABSENT here: the engine is channel-opaque (delivery lives in the
- * gateway), so the gateway merges its own channel registry into `workflow.capabilities` /
- * `x/workflow.chat` responses. Everything else enumerates REAL runtime state — no static lists.
+ * Canonical Workflow capability-catalog helpers. Runtime owns and injects the exact catalog;
+ * qlogicagent only renders and validates that snapshot for Workflow Chat.
  */
-import type { ToolDefinition } from "../../protocol/wire/chat-types.js";
-export type CapabilityCategory = "agent" | "tool" | "skill" | "mcp" | "memory" | "channel" | "control";
+export type CapabilityCategory = "agent" | "action" | "mcp" | "memory" | "channel" | "control";
 export interface CapabilityEntry {
     category: CapabilityCategory;
-    /** Workflow node kind that uses this capability. */
     kind: string;
-    /** Concrete reference: tool name / agent id / "server.tool" / memory op / channel name. */
+    /** Concrete Agent, MCP plugin/tool, memory, channel, or control reference. */
     id: string;
-    /** Human-readable name for pickers and the AI prompt. */
     label: string;
     description?: string;
-    /** JSON schema of the underlying callable's input (tools/mcp), when known. */
     paramsSchema?: Record<string, unknown>;
-    /** Prefill for add_node params when the user picks this entry. */
     paramsTemplate?: Record<string, unknown>;
+    pluginId?: string;
+    toolName?: string;
+    server?: string;
+    tool?: string;
 }
-export interface CapabilityCatalogDeps {
-    getToolManifest(): ToolDefinition[];
-    /** Available agent ids a workflow `agent` node can target (self first). */
-    listAgentIds(): {
-        id: string;
-        name?: string;
-    }[];
-    /** Project root for project-scoped skill resolution. */
-    projectRoot: string;
-}
-/** Enumerate every capability a workflow in `projectRoot` can reference right now. */
-export declare function buildCapabilityCatalog(deps: CapabilityCatalogDeps): Promise<CapabilityEntry[]>;
-/**
- * Compact catalog text for the AI graph builder's system prompt: category headers + `id — desc`
- * lines, hard-capped per category so huge tool sets don't blow the prompt (the agent uses the
- * list_capabilities tool for the long tail).
- */
+/** Render the Host-owned catalog for the AI graph builder prompt. */
 export declare function renderCatalogForPrompt(entries: CapabilityEntry[], perCategoryCap?: number): string;
-/** Refs the validator extracts from a def to check against the catalog (anti-hallucination). */
+/** Extract canonical references for anti-hallucination validation. */
 export declare function collectCapabilityRefs(def: {
     nodes: {
         id: string;
@@ -54,7 +31,7 @@ export declare function collectCapabilityRefs(def: {
     ref: string;
     nodeId: string;
 }[];
-/** Validate def refs against the catalog. Returns human-readable errors (empty = clean). */
+/** Validate canonical references against the Host-owned catalog. */
 export declare function validateCapabilityRefs(def: {
     nodes: {
         id: string;

package/dist/types/orchestration/workflow/host-executors.d.ts

@@ -1,15 +1,15 @@
 /**
  * Host-backed NodeExecutors (M3 bridge contract; plan D12/D13, spec §B).
  *
- * The engine is a pure executor: kinds that need real-world capabilities (agent / tool / http /
- * mcp / channel) are fulfilled by an injected `ExecutorHost`. In production the xiaozhiclaw gateway
+ * The engine is a pure executor: kinds that need real-world capabilities (agent / http / channel)
+ * are fulfilled by an injected `ExecutorHost`. Canonical Action execution is injected by Runtime.
  * (or the qlogicagent CLI host) provides a real host; the engine never imports those subsystems.
  *
  * These executors are REAL (not mocks): they read the node's resolved params + inputs and delegate
  * to the host. fail-loud — invoking a host-backed kind with no host throws (no silent fallback).
  */
 import type { NodeExecutor } from "./node-schema.js";
-/** The host-backed kinds. Register these into a NodeRegistry to enable agent/tool/http/mcp/channel/skill/memory/subworkflow/approval. */
+/** Host-backed canonical and imported node kinds. Runtime injects the canonical Action executor. */
 export declare const hostExecutors: Record<string, NodeExecutor>;
 /** Host-backed kind names (used by callers to know which kinds need a host). */
 export declare const HOST_BACKED_KINDS: string[];

package/dist/types/orchestration/workflow/n8n-import.d.ts

@@ -12,7 +12,6 @@ export interface N8nCredentialRequirement {
     nodeId: string;
     n8nCredentialType: string;
     label?: string;
-    suggestedVaultType: string;
 }
 export interface N8nBindingRequirement {
     models: Array<{

package/dist/types/orchestration/workflow/node-schema.d.ts

@@ -101,24 +101,21 @@ export interface ExecutorContext {
         info(m: string): void;
         warn(m: string): void;
     };
-    /** Host capabilities for host-backed node kinds (agent/tool/http/mcp/channel), D13. */
+    /** Host capabilities for host-backed and Runtime-injected node kinds. */
     host?: ExecutorHost;
     /** Cooperative cancellation for long-running host calls. */
     signal?: AbortSignal;
 }
 /**
- * Capabilities the HOST (xiaozhiclaw gateway, or the qlogicagent CLI host) provides to back node
- * kinds the engine cannot fulfil on its own. The engine stays a pure executor (plan D12/D13):
- * agent/tool/mcp/http are qlogicagent-owned host capabilities; channel/IM call back into the
- * xiaozhiclaw channel layer. fail-loud: a host-backed kind with no host throws.
+ * Capabilities the embedding HOST provides for node kinds the engine cannot fulfil on its own.
+ * Production composition belongs to the xiaozhiclaw Gateway Host; qlogicagent exports the inert
+ * executor contract and test/CLI adapters. A host-backed kind with no host fails loud.
  */
 export interface ExecutorHost {
     /** Run an agent turn. Returns the agent's structured output as DataItem(s). */
     runAgent(req: AgentHostRequest): Promise<DataItem[]>;
     /** Run the currently configured workflow/text model. The host resolves provider/API key/model. */
     runModel?(req: ModelHostRequest): Promise<DataItem[]>;
-    /** Invoke a qlogicagent tool by name. */
-    invokeTool(req: ToolHostRequest): Promise<DataItem[]>;
     /** Perform an HTTP request (credentials resolved host-side). */
     httpRequest(req: HttpHostRequest): Promise<DataItem[]>;
     /** Invoke an MCP server tool. */
@@ -161,21 +158,11 @@ export interface ModelHostRequest {
     input: DataItem[];
     signal?: AbortSignal;
 }
-export interface ToolHostRequest {
-    tool: string;
-    args: Record<string, unknown>;
-    /** True when this run's trigger is unattended — the host applies fine-grained audits (IT-7b). */
-    unattended?: boolean;
-    input: DataItem[];
-    signal?: AbortSignal;
-}
 export interface HttpHostRequest {
     method: string;
     url: string;
     headers?: Record<string, string>;
     body?: unknown;
-    /** Vault credential to inject as auth headers at execution time (D29; resolved host-side). */
-    credentialId?: string;
     signal?: AbortSignal;
 }
 export interface McpHostRequest {
@@ -211,7 +198,7 @@ export interface ApprovalHostRequest {
     /** Deadline for a decision; default 24h. What happens at the deadline is timeoutAction (default reject). */
     timeoutMs?: number;
     /** Timeout policy (default "reject"): "reject" fails the node but ANNOUNCES it (not a silent auto-deny);
-     *  "approve" auto-continues; "keepPending" stays suspended (persisted; re-prompts on restart). */
+     *  "approve" auto-continues; "keepPending" stays suspended in the current Gateway process only. */
     timeoutAction?: "approve" | "reject" | "keepPending";
     input: DataItem[];
     signal?: AbortSignal;

package/dist/types/orchestration/workflow/params-schema.d.ts

@@ -1,11 +1,8 @@
 /**
  * Node params schema — single source for "what params does each node kind take" (spec R6 / D45).
  *
- * Two schema sources, one resolver:
- *   - tool / mcp  → per-capability `paramsSchema` on the CapabilityEntry (the tool's own arg schema,
- *     validates node.params.args).
- *   - everything else (http/agent/channel/memory/if/filter/switch/transform/wait/...) → a per-KIND
- *     schema here (KIND_PARAM_SCHEMAS), validates node.params directly.
+ * Each canonical node kind has one schema in KIND_PARAM_SCHEMAS. MCP tool argument schemas are
+ * attached to Agent plugins or canonical Action choices by Runtime's Host-owned catalog.
  *
  * The schemas are a JSON-Schema subset aligned with the canvas SchemaArgsForm consumer
  * (type/enum/default/minimum/maximum/multipleOf/format/x-widget). `required` mirrors what the REAL
@@ -19,7 +16,7 @@
  *     not a hallucination) — surfaced by collectClarifications for the 待补 badge + activation gate.
  */
 import type { CapabilityEntry } from "./capability-catalog.js";
-/** Per-kind params schemas for non tool/mcp kinds. `trigger` (workflow-level trigger def) and
+/** Per-kind params schemas. `trigger` (workflow-level trigger def) and
  *  `manual` (n8n import placeholder that always fails) are intentionally excluded. */
 export declare const KIND_PARAM_SCHEMAS: Record<string, Record<string, unknown>>;
 /** An `__ASK__: 问题` sentinel — the agent honestly marking an unknown required value (AI-2).
@@ -31,13 +28,9 @@ type NodeLike = {
     params?: Record<string, unknown>;
 };
 /**
- * The schema that governs a node's params:
- *   - tool → the tool capability's paramsSchema (governs params.args).
- *   - mcp  → the "server.tool" capability's paramsSchema (governs params.args).
- *   - else → KIND_PARAM_SCHEMAS[kind] (governs params directly).
- * Returns undefined when no schema is known (e.g. a tool ref outside the catalog).
+ * Resolve the schema governing a canonical node's params.
  */
-export declare function resolveNodeParamsSchema(node: NodeLike, entries: CapabilityEntry[]): Record<string, unknown> | undefined;
+export declare function resolveNodeParamsSchema(node: NodeLike, _entries: CapabilityEntry[]): Record<string, unknown> | undefined;
 /**
  * Validate every node's params against its resolved schema. Returns human-readable Chinese errors
  * (empty = clean). Skips `trigger` (trigger def is validated elsewhere) and `manual` (placeholder).
@@ -45,7 +38,7 @@ export declare function resolveNodeParamsSchema(node: NodeLike, entries: Capabil
  */
 export declare function validateParamsAgainstSchema(def: {
     nodes: NodeLike[];
-}, entries: CapabilityEntry[]): string[];
+}, _entries: CapabilityEntry[]): string[];
 /**
  * Collect every `{{ __ASK__ }}` placeholder in a def (top-level params + one level into `args`).
  * Drives the canvas "待补" badge and the activation gate (a workflow with pending asks cannot be
@@ -69,9 +62,7 @@ export declare function collectClarifications(def: {
     question: string;
 }[];
 /**
- * Compact per-kind params hint for the AI graph-builder prompt, derived from KIND_PARAM_SCHEMAS
- * (single source — the prompt never hand-duplicates param names). tool/mcp carry per-capability
- * arg schemas (the agent reads them via list_capabilities), so they get a pointer not a field list.
+ * Compact per-kind params hint for the AI graph-builder prompt, derived from KIND_PARAM_SCHEMAS.
  */
 export declare function renderKindParamsForPrompt(): string;
 export {};

package/dist/types/orchestration/workflow/qla-executor-host.d.ts

@@ -1,15 +1,13 @@
 /**
- * QlogicagentExecutorHost — the REAL host backing host-executors (agent/tool/http/mcp/channel)
+ * QlogicagentExecutorHost backing canonical host executors and Runtime-injected Action nodes
  * with qlogicagent's actual capabilities. No mocks, no stubs (plan §1.5).
  *
  * Boundary capabilities (runAgent / invokeMcp / sendChannel) are injected so this file stays
- * decoupled from the handler host that owns Gateway delegation and the xiaozhiclaw channel
- * callback. Tool invocation goes straight through the single-source-of-truth tool registry
- * (`findTool`). fail-loud everywhere: unknown tool, missing channel host, or any rejection throws.
+ * decoupled from the Gateway Host. Missing capabilities and downstream rejections fail loudly.
  */
-import type { LLMTransport, RuntimeToolContract } from "../../runtime/ports/index.js";
+import type { LLMTransport } from "../../runtime/ports/index.js";
 import { type DataItem } from "./data-item.js";
-import type { ExecutorHost, ToolHostRequest, MemoryHostRequest, SubworkflowHostRequest, ApprovalHostRequest, WebhookWaitHostRequest } from "./node-schema.js";
+import type { ExecutorHost, MemoryHostRequest, SubworkflowHostRequest, ApprovalHostRequest, WebhookWaitHostRequest } from "./node-schema.js";
 /** Injected boundary capabilities — supplied by the handler host that owns the real runners. */
 export interface QlaExecutorHostDeps {
     /** Run one agent turn (spawn external ACP agent + sendTask). Returns the agent's text output. */
@@ -41,8 +39,6 @@ export interface QlaExecutorHostDeps {
         payload: unknown;
         signal?: AbortSignal;
     }) => Promise<unknown>;
-    /** Tool lookup supplied by the runtime host. */
-    findTool: (name: string) => RuntimeToolContract | undefined;
     /**
      * Project-scoped memory backend for the `memory` kind (spec D25). The handler host wires
      * the owning project root's memdir; absent → memory nodes fail-loud.
@@ -58,26 +54,7 @@ export interface QlaExecutorHostDeps {
     }>;
     /** D34 wait-until-webhook: suspend until the path is hit (handler owns the wake registry). */
     waitWebhook?: (req: WebhookWaitHostRequest) => Promise<Record<string, unknown>>;
-    /**
-     * IT-7b fine-grained unattended audit (unified permission engine's operation classifier).
-     * Called for every tool invocation in an UNATTENDED run; throw to refuse (fail-loud).
-     */
-    auditUnattendedTool?: (req: ToolHostRequest) => void;
-    /**
-     * Vault credential → auth headers, resolved at EXECUTION time only (D29). Absent ⇒ http
-     * nodes carrying credentialId fail-loud (never silently unauthenticated).
-     */
-    resolveCredentialHeaders?: (credentialId: string) => Record<string, string>;
     /** fetch impl; defaults to global fetch. Injectable for tests. */
     fetchImpl?: typeof fetch;
-    /**
-     * Owning workflow root (multi-root, R5):tool 节点的 cwd 必须钉在所属项目工作区。
-     * in-process 工具注册表跟随 agent 的"活动项目"全局 cwd —— 不钉的话,项目 A 的
-     * tool 节点会在项目 B 的目录里动文件(跨项目写,真机踩过:产物落错工作区)。
-     * 注入方式 = exec 工具既有的 `workdir` 参数(作者显式指定时尊重);其余工具无
-     * per-call cwd 通道,仍循全局 cwd —— 工作流里写文件的正路是 agent 节点(子进程
-     * 带根 cwd)与 exec;若需全工具 cwd 线程化,另立决策改 RuntimeToolContract。
-     */
-    workspaceCwd?: string;
 }
 export declare function createQlaExecutorHost(deps: QlaExecutorHostDeps): ExecutorHost;

package/dist/types/orchestration/workflow/workflow-bundle.d.ts

@@ -1,32 +1,18 @@
 /**
- * Portable workflow bundle (spec D23) — THE single serialization format shared by
- * export / import / save-as(duplicate) / Hub publish / Hub apply. Two invariants:
- *
- * 1. SANITIZED: credentials never leave the machine inside a bundle. Any params key that
- *    looks credential-shaped has its VALUE stripped and is recorded as a CredentialRequirement
- *    the importer must re-bind. Unknown-but-suspicious shapes fail toward stripping (§1.5:
- *    never silently carry a secret out).
- * 2. SELF-DESCRIBING: `requires` lists the capabilities (tool/agent/mcp/channel/skill) the
- *    graph references, so an importer (or the Hub apply checklist) can verify bindings
- *    BEFORE activating instead of failing mid-run.
+ * Canonical portable Workflow bundle shared by export, import, duplicate, Hub publish,
+ * and Hub apply. Bundles contain graph structure and capability references only. Runtime
+ * authentication remains owned by MCP and Provider modules and is never serialized here.
  */
 import { type WorkflowDef } from "./node-schema.js";
 import type { TriggerDef } from "./workflow-trigger.js";
 import type { ConcurrencyPolicy, WorkflowRecord } from "./workflow-store.js";
-export declare const WORKFLOW_BUNDLE_SCHEMA_VERSION = 2;
+export declare const WORKFLOW_BUNDLE_SCHEMA_VERSION = 3;
 export interface CapabilityRequirement {
-    category: "agent" | "tool" | "skill" | "mcp" | "memory" | "channel";
+    category: "agent" | "mcp" | "memory" | "channel";
     kind: string;
-    /** Concrete capability reference (tool name / agent id / "server.tool" / channel name). */
+    /** Concrete capability reference, such as an Agent id or MCP plugin/tool id. */
     ref: string;
-    /** Human-readable label shown in the apply/bind checklist. */
-    label: string;
-    nodeIds: string[];
-}
-export interface CredentialRequirement {
-    /** Best-effort type hint; v1 marks all stripped values "custom" (vault types land in IT-7). */
-    type: "apiKey" | "bearer" | "basic" | "oauth2" | "custom";
-    /** Where the value was stripped from, e.g. `节点「发飞书」 params.headers.Authorization`. */
+    /** Human-readable label shown in the apply checklist. */
     label: string;
     nodeIds: string[];
 }
@@ -38,7 +24,6 @@ export interface WorkflowBundle {
     trigger?: TriggerDef;
     concurrency?: ConcurrencyPolicy;
     requires: CapabilityRequirement[];
-    credentialsRequired: CredentialRequirement[];
     meta?: {
         author?: string;
         tags?: string[];
@@ -47,11 +32,9 @@ export interface WorkflowBundle {
         source?: "native" | "n8n";
     };
 }
-/** Placeholder left where a credential value was stripped (visibly broken > silently leaked). */
-export declare const STRIPPED_CREDENTIAL_PLACEHOLDER = "__CREDENTIAL_REQUIRED__";
-/** Derive the capability requirements a graph references (host-backed kinds only). */
+/** Derive capability requirements from canonical Agent attachments and Action nodes. */
 export declare function deriveRequirements(def: WorkflowDef): CapabilityRequirement[];
-/** Serialize a stored record into a sanitized, self-describing portable bundle. */
+/** Serialize a stored record into the canonical, credential-free bundle. */
 export declare function toWorkflowBundle(record: WorkflowRecord): WorkflowBundle;
 export interface ParsedBundle {
     name: string;
@@ -59,7 +42,6 @@ export interface ParsedBundle {
     trigger?: TriggerDef;
     concurrency?: ConcurrencyPolicy;
     requires: CapabilityRequirement[];
-    credentialsRequired: CredentialRequirement[];
 }
-/** Parse + validate an incoming bundle payload. fail-loud on malformed shapes (§1.5). */
+/** Parse and validate an incoming canonical bundle. */
 export declare function fromWorkflowBundle(payload: unknown): ParsedBundle;

package/dist/types/orchestration/workflow/workflow-controller.d.ts

@@ -1,7 +1,8 @@
 /**
- * Workflow Controller — automation driver: create / run / pause / resume + concurrency (spec §B4/B5).
+ * Workflow Controller: reusable automation lifecycle and execution engine.
  *
- * Owns workflow lifecycle on top of the WorkflowStore (persistence) and WorkflowRuntime (execution).
+ * Runtime's Gateway Host owns and constructs this controller with a project-scoped WorkflowStore.
+ * The qlogicagent executable publishes the engine but never constructs a Workflow owner.
  * Concurrency (spec §B5): when a workflow is triggered while a previous run is still in-flight, the
  * record's `concurrency` policy decides:
  *   - "skip"     -> drop the new trigger (returns status "skipped")
@@ -29,6 +30,11 @@ export interface TriggerEvent {
     type: WorkflowTriggerKind;
     payload?: Record<string, unknown>;
 }
+export interface WorkflowRunStarted {
+    workflowId: string;
+    runId: string;
+    triggerType: WorkflowTriggerKind;
+}
 /**
  * Per-run context handed to the RuntimeFactory: the trigger KIND (so the factory can wire the D15
  * permission gate — unattended kinds are restricted) plus its payload (exposed to expressions).
@@ -130,9 +136,9 @@ export declare class WorkflowController {
     /** Load a single record or throw (fail-loud lookup; used by the scheduler to re-read triggers). */
     get(id: string): Promise<WorkflowRecord>;
     /**
-     * Render a workflow as compact agent-context text (spec §B / §A `get`). Fail-loud on unknown id.
-     * This is the engine half of the agent `workflow.get`/describe action: the agent reads this and
-     * emits a WorkflowPatch against the shown `rev`.
+     * Render a workflow as compact planning context (spec §B / §A `get`). Fail-loud on unknown id.
+     * Runtime Host supplies the authoritative record; stateless planning may use this rendering to
+     * propose a WorkflowPatch against the shown `rev`.
      */
     describe(id: string, opts?: RenderOptions): Promise<string>;
     /**
@@ -150,11 +156,11 @@ export declare class WorkflowController {
     run(id: string, trigger?: TriggerEvent, opts?: {
         recordHistory?: boolean;
         reuseCache?: boolean;
+        onStarted?: (run: WorkflowRunStarted) => void | Promise<void>;
     }): Promise<RunOutcome>;
     /**
-     * Wrap a run with durable history recording (when wired). Lives at this choke point —
-     * not in the RPC handler — so cron/IM/webhook runs are recorded identically to manual
-     * ones. History writes are best-effort: a recording failure never blocks the run.
+     * Wrap a run with durable history recording (when wired). The running checkpoint is the
+     * publication barrier for lifecycle observers, and terminal history is fail-loud.
      */
     private recordRun;
     /** Cooperatively pause the in-flight run; it suspends before the next node (cache retained). */

package/dist/types/orchestration/workflow/workflow-error.d.ts

@@ -7,7 +7,7 @@
  */
 export type WorkflowErrorClass = "user" | "capability" | "network" | "system";
 /** Next-step buttons the canvas offers for an error (0 死端 — every failure has a way forward). */
-export type WorkflowErrorAction = "ai_fix" | "rerun_node" | "rerun_all" | "open_credentials" | "swap_capability";
+export type WorkflowErrorAction = "ai_fix" | "rerun_node" | "rerun_all" | "swap_capability";
 export interface WorkflowError {
     class: WorkflowErrorClass;
     /** Plain-language Chinese explanation (NO stack trace). */

package/dist/types/orchestration/workflow/workflow-render.d.ts

@@ -10,7 +10,7 @@
  *
  * Determinism (§1.5): node order follows the def's node array (stable, persisted order); param
  * keys are sorted; expressions (`{{ }}`) render verbatim so the agent can copy them into bindings.
- * Large graphs truncate with an explicit hint to call `workflow.get` for the full definition.
+ * Large graphs truncate with an explicit hint to fetch the full definition from the Gateway Host.
  */
 import type { WorkflowDef } from "./node-schema.js";
 import type { TriggerDef } from "./workflow-patch.js";

package/dist/types/orchestration/workflow/workflow-scheduler.d.ts

@@ -1,11 +1,10 @@
 /**
- * In-process workflow trigger scheduler (plan M3 trigger layer).
+ * Reusable in-process Workflow trigger scheduler (plan M3 trigger layer).
  *
- * Architecture note: scheduling lives INSIDE qlogicagent, not the gateway. This mirrors the
- * established precedent — the idle "dream" timer was deliberately moved out of the xiaozhiclaw gateway
- * into qlogicagent so the Agent owns its own timed lifecycle ("Agent 是唯一状态拥有者"). The gateway
- * remains a pure relay: it terminates external ingress (webhook HTTP, inbound IM) and forwards those
- * events here via `onWebhook` / `onImMessage`; the cron clock and the run decision are the Agent's.
+ * Production ownership lives in the Runtime Gateway Host: it constructs one project-scoped instance,
+ * owns its clock and lifecycle, and routes cron/webhook/IM/manual triggers through that instance. The
+ * qlogicagent executable only publishes this inert engine building block and never constructs a
+ * scheduler owner.
  *
  * The scheduler is the consumer of WorkflowController: on `start()` it loads every active workflow
  * (`listActive`, spec §B4 restart re-registration) and arms a timer per `schedule` trigger; on fire
@@ -35,7 +34,7 @@ export interface SchedulerDeps {
      * triggers (webhook/IM/manual) propagate their errors to the caller instead.
      */
     onError: (err: unknown, workflowId: string) => void;
-    onRunStarted?: (workflowId: string, triggerType: string) => void;
+    onRunStarted?: (workflowId: string, triggerType: string, runId: string) => void | Promise<void>;
     onRunCompleted?: (outcome: RunOutcome, triggerType: string) => void;
     onRunFailed?: (workflowId: string, triggerType: string, err: unknown) => void;
     /**
@@ -96,7 +95,7 @@ export declare class WorkflowScheduler {
      * into the run payload so downstream nodes can reference `$trigger`.
      */
     onImMessage(channel: string, text: string, payload?: Record<string, unknown>): Promise<RunOutcome[]>;
-    /** Manually trigger a single workflow (the agent's `workflow.run`). Errors propagate to caller. */
+    /** Manually trigger a single workflow for the owning Runtime Host. Errors propagate to caller. */
     triggerManual(id: string, payload?: Record<string, unknown>): Promise<RunOutcome>;
     private matchingIds;
     private registerTrigger;
@@ -108,4 +107,5 @@ export declare class WorkflowScheduler {
      */
     private passesRateLimit;
     private runWithLifecycle;
+    private reportLifecycleCallbackError;
 }

package/dist/types/orchestration/workflow/workflow-store.d.ts

@@ -1,10 +1,9 @@
 /**
- * Workflow Store — persist workflow definitions + lifecycle state to disk (spec §B4).
+ * Workflow Store: project-scoped persistence used by Runtime's Gateway Workflow Host.
  *
- * Stored at `<project>/.qlogicagent/workflows/<workflowId>/workflow.json`. Listing enumerates
- * subdirectories (mirrors product-persistence.ts). The store is the single source of truth for a
- * workflow's definition, its active flag, and its concurrency policy; the gateway re-registers
- * triggers for every active workflow on restart (spec §B4).
+ * Stored at `<project>/.qlogicagent/workflows/<workflowId>/workflow.json`. Within a Runtime Host
+ * project service, this is the single source of truth for the workflow definition, active flag,
+ * and concurrency policy. Runtime re-registers active triggers when that service starts.
  *
  * fail-loud: missing id on save throws; load returns undefined only for a genuinely absent record.
  */
@@ -15,10 +14,10 @@ export type ConcurrencyPolicy = "queue" | "skip" | "parallel";
 export interface WorkflowRecord {
     id: string;
     name: string;
-    /** Owning user (llmrouter id via resolveActiveOwnerUserId, D38). Absent on legacy records. */
+    /** Owning user, resolved by the Runtime Host. */
     owner?: string;
     def: WorkflowDef;
-    /** Active workflows have their triggers registered by the gateway (spec §B4). */
+    /** Active workflows have their triggers registered by the Runtime Gateway Host. */
     active: boolean;
     concurrency: ConcurrencyPolicy;
     /** The workflow's trigger (set via a WorkflowPatch set_trigger op; spec §C/D7). */
@@ -75,7 +74,7 @@ export declare class WorkflowStore {
     /** Load a record or throw (fail-loud lookup for callers that require existence). */
     require(id: string): Promise<WorkflowRecord>;
     list(): Promise<WorkflowRecord[]>;
-    /** Active workflows the gateway must re-register triggers for after a restart (spec §B4). */
+    /** Active workflows the Runtime Gateway Host re-registers when the project service starts. */
     listActive(): Promise<WorkflowRecord[]>;
     delete(id: string): Promise<void>;
 }