@qilin-agent/base 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,58 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/bundle/base/README.md
+/:
+  en: 9287daaf4ca81ac3
+  zh: b91402a7e13adb98
+/qilin-base:
+  en: f1248f2a147590d3
+  zh: 45cf386dffbdd068
+/qilin-base/summary:
+  en: 654e632a4443a17f
+  zh: d0a1310c89a00ef2
+/qilin-base/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-base/use-this-package:
+  en: 064dc51cda83341e
+  zh: 968ea2882bf2aa1a
+/qilin-base/use-this-package/a-minimal-custom-profile:
+  en: 1372d66f5c853fbb
+  zh: 0d6835f20370011f
+/qilin-base/use-this-package/what-you-get:
+  en: d0a31cf2a4b3c85a
+  zh: f7ef5358f854db3f
+/qilin-base/use-this-package/shell-tools-per-platform:
+  en: 2dce12f82d6ee955
+  zh: d4599eb899a3cd88
+/qilin-base/use-this-package/changing-the-defaults:
+  en: 96a55abd5f7007dd
+  zh: d94f020708c38a17
+/qilin-base/understand-the-implementation:
+  en: 094cfca8e26a0042
+  zh: de435e3e38420c01
+/qilin-base/understand-the-implementation/composition-mechanics:
+  en: fd37bc66e39ac5e7
+  zh: 1a039afb8bf2d517
+/qilin-base/understand-the-implementation/platform-gating:
+  en: f8f55ee5092e17ed
+  zh: 02d82b43a871d02a
+/qilin-base/understand-the-implementation/source-map:
+  en: a8efda71d444155e
+  zh: c8221593709fbb99
+/qilin-base/further-exploration:
+  en: 42df9b1749f17c7a
+  zh: 063be5205d8f5b94
+/qilin-base/model-experience:
+  en: f6c4d2609b5f4bb6
+  zh: 869a9565a133fb01
+/qilin-base/model-experience/kv-cache-effect:
+  en: e6e907c99df7cd0a
+  zh: f19f2f84a5f95177
+/qilin-base/known-limitations-and-deferred-work:
+  en: b10a276d7d7d7e41
+  zh: e49305f24f239b0d
+/qilin-base/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+---
+description: "The shared qilin core: model access, tools, durable sessions, and safety defaults for every qilin --profile surface, for users composing or customizing a profile."
+kind: "package-bundle"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/base
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Every base-backed `qilin --profile` surface runs on `qilin-base`, so those surfaces share a model connection, the full tool set, durable session history, and workspace safety defaults. The shipped `sdk-minimal` profile deliberately uses a complete standalone tree instead. You rarely touch this bundle directly — shipped base-backed profiles already include it, and a custom base-backed profile names it first. When you need different defaults, change your profile patch or add a later bundle; this package is not a library you import.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+You get the qilin core automatically: the shipped `web`, `headless`, `sdk`, and `acp` profiles already include it, and a custom profile names it as its first bundle. After that, everything works with no further configuration.
+
+### A minimal custom profile
+
+To build a profile on the shared core, create a profile with a `package.json` that names `@qilin-agent/base` first:
+
+```json
+{
+  "name": "my-profile",
+  "private": true,
+  "qilin": {
+    "profile": {
+      "bundles": ["@qilin-agent/base"]
+    }
+  }
+}
+```
+
+Run `qilin --profile my-profile "your task"` and you get a working agent with model access, tools, persistence, and the default permission policy. The shipped `web`, `headless`, `sdk`, and `acp` profiles are created for you on first use. To add more bundles, run `qilin plugin --profile <name> add <package>`; in-box bundles resolve from the qilin installation. The profile contract is documented in the [app-boot profile section](../../boot/app-boot/README.md).
+
+### What you get
+
+Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, public HTTP(S) fetch, subagents, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Web fetch runs without per-call approval; its provider rejects non-public destinations. Feedback stays in the Session log. [OTel session upload](../../session/session-telemetry-otel/README.md) defaults to `FEEDBACK_ONLY` for all users, including `deepseek-official`: new text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including context. Later records wait for the next explicit feedback; sending an authorized batch needs no further interaction or model call. `DISABLED` prevents OTel capture. The default-on [DeepSeek session-log contributor](../../session/session-log-deepseek/README.md) remains a separate request path.
+
+Default file editing uses `read`, `write`, and `edit`. The `str_replace_editor` tool remains available as an explicit opt-in. To add it to a base-backed profile, put this entry in the profile, home, or invocation patch:
+
+```yaml
+- insert:
+    - id: tool-str-replace-editor
+      name: '@qilin-agent/tool-str-replace-editor'
+      config:
+        maxOutputChars: 16000
+```
+
+The bundle mounts [MCP resources](../../mcp/mcp-resources/README.md) once. Configure only [MCP client entries](../../mcp/mcp-client/README.md) for the servers you need. Clients mounted by another provider also count as configured in their scope. Callers with no configured server in scope receive no MCP tools or prompt text.
+
+### Shell tools per platform
+
+On macOS and Linux you get the bash shell tools; on Windows you get the PowerShell twins instead, so exactly one shell stack is available per machine. The safety behavior is identical on every platform. A Windows host that prefers the unconfined PowerShell executor can switch the shell rows in its profile patch — the switch must disable both PowerShell rows and re-enable both bash rows, otherwise the profile fails to load.
+
+### Changing the defaults
+
+To change what a profile built on this core provides — a different default model, a stricter permission mode, extra or fewer tools — edit your profile's `cordis.patch.yml` or add a later bundle. Each patch entry replaces the target's whole configuration, so restate every setting you want to keep. Keep the sandboxed filesystem provider as the single file-write path: adding the plain filesystem provider on top of it makes the profile fail to load.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The bundle is a static patch document: one `insert` list applied over the empty profile root. It mounts no service, emits no events, and holds no mutable state; each inserted row's package owns that row's behavior and invariants.
+
+### Composition mechanics
+
+A patch replaces the targeted row's whole `config` rather than merging into it. Later bundle layers and the user's profile `cordis.patch.yml` override rows by id, with the last write winning per row. Rows whose value differs by mode do not live here: each mode bundle restates its complete configuration, keeping any single row down to one bundle layer plus the user's. The full row set and its rationale are documented inline in [`cordis.patch.yml`](cordis.patch.yml); the [generated composition graph](../../../apps/cli/composition.md) renders it.
+
+### Platform gating
+
+The patch gates the two shell stacks by platform on its own rows: `bash-sandbox` and `tool-bash` carry `disabled: !!js process.platform === 'win32'`, and their twins `pwsh-sandbox` and `tool-pwsh` mount on win32 only with the inverted expression. The permission surface stays identical to POSIX: the sandbox policy executes the same file-effect policy through the Windows ACL restricted-token runner (`qilin-sandbox-local` → `@qilin-agent/sandbox-windows-acl`), and `fs-sandbox` keeps fencing `ctx.fs` writes — mounting `qilin-fs-local` alongside it would double-register `ctx.fs` and fail the load.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | The bundle substance: the base plugin rows, with per-row rationale as inline comments |
+| [`src/index.ts`](src/index.ts) | Package entry; carries no runtime API |
+| [`tests/base.spec.ts`](tests/base.spec.ts) | Manifest declaration and platform-gating checks |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you want to go deeper into profiles, the surfaces built on this core, or the exact composition.
+
+- [app-boot profile section](../../boot/app-boot/README.md) — how profiles are resolved, layered, and customized.
+- [Bundle package map](../README.md) — the surfaces built on this core.
+- [Generated composition graph](../../../apps/cli/composition.md) — the exact plugin set each shipped profile uses.
+- [Profile plugin bundles note](../../../.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md) — the profile and bundle composition design.
+- [Codex and Claude Code provider bundles](../../subagent/README.md) — optional provider bundles you can install on top.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through each inserted row's package, which owns that row's model-facing behavior.
+
+#### KV Cache effect
+
+The bundle itself adds no request prefix; each inserted row's package owns any cache effect.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits tell you when the core needs extra care or where an override must go. They are current package constraints, not a general comparison or a task backlog.
+
+- **Overrides replace whole settings blocks** — a patch entry replaces the target's entire configuration, so your override must restate every setting you want to keep; nothing merges automatically.
+- **Per-surface settings belong to the surface's bundle** — a default that differs between the web GUI and headless mode lives in that surface's bundle, not in the shared core.
+- **Windows temp grants are private per-session subdirectories** — `workspace-write` confines writes to the workspace plus the session's own temp subdirectory (`<temp>\qilin-<hash>`, TMP/TEMP rewritten for confined children); `read-only` grants nothing. See `@qilin-agent/sandbox-windows-acl`.
+- **Adding the plain filesystem provider on top of the sandboxed one fails the profile** — the two register the same service, so the profile refuses to load; use one or the other.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,144 @@
+---
+description: "共享的 qilin 核心：为每个 qilin --profile 表层提供模型访问、工具、持久会话与安全默认值，供用户组合或定制 profile。"
+kind: "package-bundle"
+---
+
+# @qilin-agent/base
+
+[English](README.md) | 中文
+
+## 概述
+
+每个基于 base 的 `qilin --profile` 表层都运行在 `qilin-base` 上，因此这些表层共享模型连接、完整工具集、持久会话历史和 workspace 安全默认值。随附的 `sdk-minimal` profile 刻意改用完整的独立配置树。你通常不直接操作本组合包——随发行版交付的基于 base 的 profile 已经包含它，自定义的基于 base 的 profile 则把它放在第一位。需要其他默认值时，应修改自己的 profile patch 或添加后续组合包；本包不是供导入的库。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+你会自动获得 qilin 核心：随发行版交付的 `web`、`headless`、`sdk` 与 `acp` profile 已包含它，自定义 profile 则把它列为第一个组合包。之后一切无需任何额外配置即可工作。
+
+### 最小自定义 profile
+
+要在共享核心之上构建 profile，请创建一个 profile，其 `package.json` 把 `@qilin-agent/base` 列在首位：
+
+```json
+{
+  "name": "my-profile",
+  "private": true,
+  "qilin": {
+    "profile": {
+      "bundles": ["@qilin-agent/base"]
+    }
+  }
+}
+```
+
+运行 `qilin --profile my-profile "your task"`，你就得到一个可用的 agent（智能体），带模型访问、工具、持久化与默认权限策略。随发行版交付的 `web`、`headless`、`sdk` 与 `acp` profile 会在首次使用时为你创建。要添加更多组合包，运行 `qilin plugin --profile <name> add <package>`；内置组合包从 qilin 安装目录解析。profile 约定见 [app-boot 的 profile 章节](../../boot/app-boot/README.zh.md)。
+
+### 你得到什么
+
+开箱即用，基于本核心构建的每个 profile 都提供：DeepSeek 模型连接（提供方与模型可配置，你还可以在设置中启用额外提供方）、完整工具集——文件编辑、shell 命令、web 搜索、公开 HTTP(S) 抓取、subagent、任务与目标跟踪——可跨重启存活的持久会话，以及默认权限策略：把文件写入限制在工作区内，危险操作前征询许可。Web 抓取无需逐次审批，其提供方会拒绝非公开目的地址。反馈保存在会话日志中。[OTel 会话上传](../../session/session-telemetry-otel/README.zh.md)对所有用户默认使用 `FEEDBACK_ONLY`，包括 `deepseek-official`：新的文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范会话日志前缀，包含上下文。后续记录等待下一次显式反馈；发送已授权批次无需进一步交互或模型调用。`DISABLED` 阻止 OTel 捕获。默认开启的 [DeepSeek 会话日志贡献器](../../session/session-log-deepseek/README.zh.md)仍是独立的请求路径。
+
+默认文件编辑使用 `read`、`write` 和 `edit`。`str_replace_editor` 工具仍可显式启用。要将它加入基于 base 的 profile，请在 profile、home 或逐次调用 patch 中添加以下条目：
+
+```yaml
+- insert:
+    - id: tool-str-replace-editor
+      name: '@qilin-agent/tool-str-replace-editor'
+      config:
+        maxOutputChars: 16000
+```
+
+本 bundle 统一挂载 [MCP 资源](../../mcp/mcp-resources/README.zh.md)一次。只需为所需服务器配置 [MCP 客户端条目](../../mcp/mcp-client/README.zh.md)。其他提供方挂载的客户端在所属作用域中也属于已配置状态。调用方作用域中没有已配置服务器时，不会获得 MCP 工具或提示词文本。
+
+### 各平台的 shell 工具
+
+在 macOS 与 Linux 上你获得 bash shell 工具；在 Windows 上则获得对应的 PowerShell 孪生工具，因此每台机器恰好有一套 shell 栈。各平台的安全行为完全一致。偏好不受沙盒约束的 PowerShell 执行器的 Windows 主机可以在其 profile patch 中切换 shell 行——切换必须同时禁用两个 PowerShell 行并重新启用两个 bash 行，否则 profile 无法加载。
+
+### 更改默认值
+
+要改变基于本核心构建的 profile 提供的内容——不同的默认模型、更严格的权限模式、更多或更少的工具——请编辑 profile 的 `cordis.patch.yml` 或添加后面的组合包。每个 patch 条目会替换目标的整个配置，因此请重述每个想保留的设置。保持沙箱化文件系统提供方作为唯一的文件写入路径：在其之上再添加普通文件系统提供方会导致 profile 加载失败。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本组合包是一份静态 patch 文档：一个应用到空 profile 根之上的 `insert` 列表。它不挂载任何服务、不发出任何事件、也不持有任何可变状态；每条插入行所属的包负责该行的行为与不变式。
+
+### 组合机制
+
+patch 会替换目标行的整个 `config`，而不是合并进它。后续组合包层与用户的 profile `cordis.patch.yml` 按 id 覆盖行，每行最后一次写入生效。按模式取值不同的行不属于这里：每个模式组合包重述自己的完整配置，让任何单一行最多只属于一个组合包层加用户层。完整行集合及其设计依据以行内注释写在 [`cordis.patch.yml`](cordis.patch.yml) 里；[生成的组合图](../../../apps/cli/composition.md)负责渲染它。
+
+### 平台门控
+
+patch 在自身上按平台门控两个 shell 栈：`bash-sandbox` 与 `tool-bash` 携带 `disabled: !!js process.platform === 'win32'`，孪生行 `pwsh-sandbox` 与 `tool-pwsh` 以取反的表达式仅在 win32 挂载。权限面与 POSIX 完全一致：沙箱策略通过 Windows ACL 受限令牌 runner（`qilin-sandbox-local` → `@qilin-agent/sandbox-windows-acl`）执行相同的文件效果策略，`fs-sandbox` 继续围栏 `ctx.fs` 写入——在其旁再挂载 `qilin-fs-local` 会重复注册 `ctx.fs` 并在加载时失败。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | 组合包的实体：基础插件行，附以行内注释说明各行依据 |
+| [`src/index.ts`](src/index.ts) | 包入口；不携带任何运行时 API |
+| [`tests/base.spec.ts`](tests/base.spec.ts) | manifest（元数据清单）声明与平台门控检查 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当你想深入了解 profile、基于本核心构建的表层或确切组合时，阅读以下页面。
+
+- [app-boot 的 profile 章节](../../boot/app-boot/README.zh.md)——profile 如何解析、分层与定制。
+- [组合包索引](../README.zh.md)——基于本核心构建的表层。
+- [生成组合图](../../../apps/cli/composition.md)——随发行版交付的每个 profile 使用的确切插件集合。
+- [Profile 组合包设计笔记](../../../.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md)——profile 与组合包的组合设计。
+- [Codex 与 Claude Code 提供方组合包](../../subagent/README.zh.md)——可叠加安装的可选提供方组合包。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过每条插入行所属的包间接产生影响，由各包负责其行的模型可见行为。
+
+#### KV Cache 影响
+
+组合包本身不添加任何请求前缀；每条插入行所属的包负责各自的缓存影响。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制告诉你核心何时需要额外注意、覆盖应放在哪里。它们是当前包约束，不是通用对比或任务积压。
+
+- **覆盖会替换整个设置块**——patch 条目会替换目标的整个配置，因此你的覆盖必须重述每个想保留的设置；不会自动合并。
+- **按表层的设置属于该表层的组合包**——web GUI 与 headless 模式取值不同的默认值放在对应表层的组合包里，而不是共享核心。
+- **Windows 的临时目录授权是按会话的私有子目录**——`workspace-write` 把写入限制在工作区与会话自己的 temp 子目录（`<temp>\qilin-<hash>`，受限子进程的 TMP/TEMP 被改写）；`read-only` 不授予任何临时目录写入权限。见 `@qilin-agent/sandbox-windows-acl`。
+- **在沙箱化文件系统提供方之上添加普通提供方会导致 profile 失败**——两者注册同一个服务，profile 因此拒绝加载；二选一。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/cordis.patch.yml

@@ -0,0 +1,518 @@
+# The qilin-base bundle patch: the shared core of each base-backed profile, applied as
+# ONE insert over the empty profile root. Later bundle patches and the user's
+# profile cordis.patch.yml address these rows by id, with the last write
+# winning per row.
+#
+# A patch replaces the targeted row's whole `config` rather than merging into
+# it, so a row whose value differs by mode does NOT live here: it belongs to
+# each mode bundle, keeping any single row down to one bundle layer plus the
+# user's. Mode-specific rows appear below only with shared plugin identity and
+# neutral defaults; each mode bundle restates its complete configuration.
+#
+# Row order carries no load semantics (activation is service-availability
+# driven); the grouping is for readers.
+
+- insert:
+    - id: tool-plugin-manager
+      name: '@qilin-agent/plugin-manager/tools'
+      disabled: true
+
+    - id: plugin-manager
+      name: '@qilin-agent/plugin-manager'
+      disabled: !!js "!ctx.get('profileContext')"
+
+    - id: timer
+      name: '@qilin-agent/kylin-plugin-timer'
+
+    # Profile configuration reloads by default; module roots are opt-in.
+    - id: hmr
+      name: '@qilin-agent/hmr'
+      disabled: !!js "!ctx.get('profileContext')"
+      config:
+        root: []
+
+    - id: llm
+      name: '@qilin-agent/llm'
+
+    - id: deepseek-llm-api-extensions
+      name: '@qilin-agent/deepseek-llm-api-extensions'
+
+    - id: session
+      name: '@qilin-agent/session'
+
+    - id: session-log-deepseek
+      name: '@qilin-agent/session-log-deepseek'
+
+    - id: typert
+      name: '@qilin-agent/typert-registry'
+
+    - id: typert-loader
+      name: '@qilin-agent/typert-loader'
+
+    - id: typert-gateway
+      name: '@qilin-agent/api-gateway'
+
+    - id: session-title
+      name: '@qilin-agent/session-title'
+      config:
+        fallbackMaxWords: 5
+        fallbackMaxBytes: 40
+        maxTitleBytes: 80
+
+    - id: session-title-llm
+      name: '@qilin-agent/session-title-first-prompt-llm'
+      config:
+        targetWords: 5
+        targetCjkCharacters: 10
+        maxInputBytes: 4096
+        maxOutputTokens: 64
+        timeoutMs: 60000
+
+    - id: user-questions
+      name: '@qilin-agent/user-questions'
+
+    - id: agent
+      name: '@qilin-agent/agent'
+
+    - id: plugin-package-inventory-deepseek
+      name: '@qilin-agent/plugin-package-inventory-deepseek'
+
+    # The transport-independent default for Agents created by entry points.
+    # Settings may supply a saved selection; consumers read it at creation time.
+    - id: agent-default-model
+      name: '@qilin-agent/agent-default-model'
+      config:
+        provider: deepseek-official
+        model: deepseek-flash
+
+    - id: jobs
+      name: '@qilin-agent/jobs-local'
+
+    - id: llm-retry
+      name: '@qilin-agent/llm-retry'
+
+    # User-settings document (`$QILIN_HOME/settings.yaml`, hot-reloaded): a
+    # `llm-deepseek:` or `llm-pi-ai:` section there overrides the adapter entries
+    # below without a restart, and is what the web Models page writes.
+    - id: settings
+      name: '@qilin-agent/settings-file'
+
+    # Credential sources: inherited environment over the managed
+    # `$QILIN_HOME/.credentials.yaml`, with project and user `.env` fallbacks.
+    # Adapters resolve references per request; the Models page writes only the
+    # managed document, which is never materialized into the process environment.
+    - id: credentials
+      name: '@qilin-agent/credentials-local'
+
+    # The pi-ai multi-provider twin, mounted dormant: zero routes (and no extra
+    # models in the picker) until a `llm-pi-ai:` settings section supplies provider
+    # profiles — then those routes register live, keys resolving per request
+    # through their apiKeyEnv references, and drop again when the section empties.
+    # Supplying those profiles is exactly what the web Models page does. Which
+    # adapters exist is composition; which providers run is the user's settings
+    # document.
+    - id: llm-pi-ai
+      name: '@qilin-agent/llm-pi-ai'
+
+    - id: session-persistence-jsonl
+      name: '@qilin-agent/session-persistence-jsonl'
+      config:
+        root: !!js qilinHomePath('sessions')
+
+    # Durable image bytes live outside the append-only session log. Messages
+    # keep content-addressed references that this shared backend resolves for
+    # provider requests and authorized history reads.
+    - id: attachment-local
+      name: '@qilin-agent/attachment-local'
+
+    # Full-text session search is opt-in. `openAt: never` keeps
+    # ctx.sessionQuery mounted — exact reads, titles, and lineage traces
+    # (session export, subagent-fork Workspace inheritance) stay available —
+    # while search calls fail with SESSION_QUERY_SEARCH_DISABLED and SQLite is
+    # never opened; the Web sidebar search matches titles and workspace names
+    # only. Deployments enabling content search override `openAt` to
+    # `first-search` or `startup` in a later patch layer (profile
+    # cordis.patch.yml or a --patch overlay), typically with a durable `path`.
+    - id: session-query-sqlite
+      name: '@qilin-agent/session-query-sqlite'
+      config:
+        path: ':memory:'
+        openAt: never
+
+    # Shared projection registry: subagent catalog identity (mode/label) folds
+    # through its registered units, so the `list_agents` surface below fails
+    # loud without it; web layers reuse this same mount for list rows.
+    - id: session-projection
+      name: '@qilin-agent/session-projection'
+
+    # Durable KV storage: the storage hub, the json backend, and the
+    # schema-validated domain form over them. Session-layer persistence (the
+    # projection cache below; workspace in web layers)
+    # routes through this stack, so it belongs to the shared base.
+    - id: storage
+      name: '@qilin-agent/storage'
+
+    - id: storage-json
+      name: '@qilin-agent/storage-json'
+      config:
+        root: !!js qilinHomePath('storages')
+
+    - id: storage-domain
+      name: '@qilin-agent/storage-domain'
+      config:
+        backend: json
+
+    # Persisted projection cache: throttled write-behind over the
+    # session_projcache domain (per-record layout — one version-stamped
+    # checkpoint document per session), serving the session listing's
+    # projection column.
+    - id: session-projection-cache
+      name: '@qilin-agent/session-projection-cache'
+      config:
+        writeEveryEvents: 200
+        writeIntervalMs: 5000
+
+    - id: otel
+      name: '@qilin-agent/otel'
+
+    # OTel releases a Session-log prefix only after explicit user feedback,
+    # regardless of model provider. Ordinary activity never triggers capture.
+    # QILIN_TELEMETRY_OTLP_URL overrides the production endpoint. A non-empty
+    # QILIN_TELEMETRY_DISABLED — any value, including '0'/'false' — opts the
+    # process out (the launchers patch the row disabled; config cannot disable
+    # a row). Exports carry the harness home's anonymous user id ($QILIN_HOME/.anonymous-user-id,
+    # random UUID; delete the file to reset the identity) as the Resource's
+    # user.id. Byte-bounded batching may turn an authorized prefix into
+    # several HTTP requests. Requests run serially; each has its own 1s
+    # transport timeout and 1.5s watchdog. A watchdog does not release the
+    # active request slot. The outer 3s shutdown deadline stops queued sends;
+    # large prefixes or an unsettled transport may leave records unsent.
+    # Every CLI exit path drains by disposing the root on SIGINT/SIGTERM.
+    - id: session-telemetry-otel
+      name: '@qilin-agent/session-telemetry-otel'
+      config:
+        mode: !!js process.env.QILIN_TELEMETRY_MODE || 'FEEDBACK_ONLY'
+        shutdownTimeoutMillis: 3000
+        maxRequestBytes: 4000000
+        exporter:
+          url: !!js process.env.QILIN_TELEMETRY_OTLP_URL ?? 'https://dsh-otel-collector.deepseeksvc.com/v1/logs'
+          compression: gzip
+          timeoutMillis: 1000
+        processor:
+          scheduledDelayMillis: 10000
+          maxQueueSize: 2048
+          maxExportBatchSize: 2048
+          exportTimeoutMillis: 1500
+
+    - id: subprocess
+      name: '@qilin-agent/subprocess-local'
+
+    # Every shipped CLI mode starts with the same file-effect boundary.
+    # The environment remains an explicit deployment override; otherwise fresh
+    # sessions pin workspace-write + ask through the permission service below.
+    - id: sandbox
+      name: '@qilin-agent/sandbox-local'
+
+    - id: sandbox-policy
+      name: '@qilin-agent/sandbox-policy'
+      config:
+        mode: !!js process.env.QILIN_PERMISSION_MODE ?? 'workspace-write'
+        workspaceRoot: !!js process.cwd()
+
+    - id: bash-sandbox
+      name: '@qilin-agent/bash-sandbox'
+      disabled: !!js process.platform === 'win32'
+      config:
+        timeoutMs: 60000
+
+    - id: pwsh-sandbox
+      name: '@qilin-agent/pwsh-sandbox'
+      disabled: !!js process.platform !== 'win32'
+
+    - id: approval
+      name: '@qilin-agent/user-approval'
+      config:
+        policy: !!js "(process.env.QILIN_PERMISSION_MODE ?? 'workspace-write') === 'danger-full-access' ? 'never' : 'ask'"
+
+    - id: permission
+      name: '@qilin-agent/permission-presets'
+      config:
+        presets:
+          read-only:
+            sandbox: read-only
+            approval: ask
+          workspace-write:
+            sandbox: workspace-write
+            approval: ask
+          danger-full-access:
+            sandbox: danger-full-access
+            approval: never
+
+    - id: shell-env
+      name: '@qilin-agent/shell-env'
+
+    - id: tool-bash
+      name: '@qilin-agent/tool-bash'
+      disabled: !!js process.platform === 'win32'
+
+    - id: tool-pwsh
+      name: '@qilin-agent/tool-pwsh'
+      disabled: !!js process.platform !== 'win32'
+
+    - id: tool-jobs
+      name: '@qilin-agent/tool-jobs'
+
+    # The model-facing "show me that" tool: its requests ride a Remote stream to
+    # the browser's Sidebar, so the service and the tool share one host row.
+    - id: sidebar-opens
+      name: '@qilin-agent/sidebar-opens'
+
+    - id: fs-observation-policy
+      name: '@qilin-agent/fs-observation-policy'
+
+    - id: tool-fs
+      name: '@qilin-agent/tool-fs'
+
+    - id: tool-fs-search
+      name: '@qilin-agent/tool-fs-search'
+      config:
+        sampleOverCapGlobResults: false
+
+    - id: agent-instructions
+      name: '@qilin-agent/agent-instructions'
+      config:
+        maxBytes: 65536
+
+    - id: skill
+      name: '@qilin-agent/skill'
+
+    - id: skill-filesystem
+      name: '@qilin-agent/skill-filesystem'
+
+    - id: skill-badge
+      name: '@qilin-agent/skill-badge'
+      disabled: true
+
+    - id: tool-skill
+      name: '@qilin-agent/tool-skill'
+
+    - id: commands
+      name: '@qilin-agent/commands'
+
+    - id: command-feedback
+      name: '@qilin-agent/command-feedback'
+
+    - id: goal
+      name: '@qilin-agent/goal'
+
+    - id: goal-round-driver
+      name: '@qilin-agent/goal-round-driver'
+
+    - id: command-goal
+      name: '@qilin-agent/command-goal'
+
+    - id: plan-mode
+      name: '@qilin-agent/plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed only to keep the request shape stable. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+    - id: token-meter
+      name: '@qilin-agent/token-meter'
+
+    - id: compaction-basic
+      name: '@qilin-agent/compaction-basic'
+
+    # Human `/compact`: one useful reduction below the automatic threshold. Backend
+    # independent, so it follows whichever compaction service this leaf mounts.
+    - id: command-compact
+      name: '@qilin-agent/command-compact'
+
+    - id: subagent
+      name: '@qilin-agent/subagent'
+
+    - id: subagent-spawn-in-process
+      name: '@qilin-agent/subagent-spawn-in-process'
+      config:
+        providerName: spawn
+
+    - id: subagent-fork-in-process
+      name: '@qilin-agent/subagent-fork-in-process'
+      config:
+        providerName: fork
+
+    # Continuable background children are selected per delegation tool. The
+    # separately loaded follow-up tool registers the one global `send_message`.
+    - id: tool-subagent-control
+      name: '@qilin-agent/tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@qilin-agent/tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@qilin-agent/tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    # Fork omits model selection so provider/model stay equal to the parent and
+    # the inherited history remains eligible for KV Cache reuse. This base row
+    # stays one-shot; preset layers may select continuable mode without adding a
+    # child-only system-prompt section or tool schema ahead of that history.
+    # See .agents/notes/implemented/feature/2026-08-18-model-selected-subagent-routes.md
+    # and .agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md.
+    - id: tool-subagent-fork
+      name: '@qilin-agent/tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: one-shot
+
+    - id: ptc-runtime
+      name: '@qilin-agent/ptc-runtime-node'
+
+    - id: workflow-ptc
+      name: '@qilin-agent/workflow-ptc'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@qilin-agent/tool-workflow'
+
+    - id: timeout-policy
+      name: '@qilin-agent/tool-call-timeout-policy'
+
+    - id: spill-local
+      name: '@qilin-agent/spill-local'
+
+    - id: spill-policy
+      name: '@qilin-agent/spill-policy'
+      config:
+        maxInlineTokens: 12500
+
+    # Durability checkpoints before each model request and top-level dispatch.
+    - id: session-checkpoint-policy
+      name: '@qilin-agent/session-checkpoint-policy'
+
+    # Compacts oversized tool results before the broader conversation compactor
+    # runs, preserving the model-visible result within the configured budget.
+    - id: tool-result-pruner
+      name: '@qilin-agent/compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+    # When an image-capable route rejects a request as over its image budget,
+    # replace the oldest images with placeholders on the surface and retry.
+    - id: image-offload
+      name: '@qilin-agent/compaction-image-offload'
+
+    - id: tool-todo
+      name: '@qilin-agent/tool-todo'
+      config:
+        allowParallelInProgress: true
+
+    # Persisted same-session goals reach the model and the slash menu here; the
+    # domain, driver, and `/goal` command are above.
+    - id: tool-goal
+      name: '@qilin-agent/tool-goal'
+
+    # Fresh-agent Ralph iteration over a build-time-fixed script. Off by
+    # default: the tool description restricts `ralph` to runs the human
+    # explicitly asked for, and completion is a worker self-report, not an
+    # independent evaluation. An overlay row restores it for a base-backed
+    # profile (`$QILIN_HOME/cordis.patch.yml`, or a `--patch <file>`):
+    #   - id: tool-ralph
+    #     disabled: false
+    - id: tool-ralph
+      name: '@qilin-agent/tool-ralph'
+      disabled: true
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+    # Consecutive-repeat reminders on the tool chain.
+    - id: repeat-tool-reminder
+      name: '@qilin-agent/repeat-tool-reminder'
+      config:
+        thresholds: [3, 5, 8]
+        argumentsPreviewChars: 500
+
+    # The shared base enables the stable model-facing web_search and web_fetch
+    # tools. The Web app disables this host row and composes both tools per agent
+    # preset; products with a stricter network policy override tool-web. DeepSeek
+    # search resolves the same DEEPSEEK_API_KEY
+    # credential the Models page manages for chat, at each search; its Messages
+    # endpoint is separate from the chat-completions endpoint, so it takes its own
+    # base-URL override. Anonymous fetch accepts only public HTTP(S) destinations,
+    # resolves and validates every destination, and pins every actual connection.
+    # Search is a full auxiliary model request with server-side retrieval, so this
+    # shipped DeepSeek route gets 60s while the provider-neutral tool default
+    # remains 30s.
+    - id: web
+      name: '@qilin-agent/web'
+      config:
+        searchProvider: deepseek-official
+        fetchProvider: http
+
+    - id: web-search-deepseek
+      name: '@qilin-agent/web-search-deepseek'
+      config:
+        apiKeyEnv: DEEPSEEK_API_KEY
+
+    - id: web-fetch-http
+      name: '@qilin-agent/web-fetch-http'
+
+    - id: tool-web
+      name: '@qilin-agent/tool-web'
+      config:
+        fetch: true
+        searchTimeoutMs: 60000
+
+    - id: mcp-resources
+      name: '@qilin-agent/mcp-resources'
+
+    # ── rows every mode mounts, whose values each overlay may state ──────────────
+
+    # The tool registry. Presentation mode is a deployment choice; omitting it here
+    # keeps the schema default (native).
+    - id: tools
+      name: '@qilin-agent/tools'
+
+    # The deployment persona is a deployment choice; plan-mode and tool plugins own
+    # their own prompt sections.
+    - id: system-prompt
+      name: '@qilin-agent/system-prompt'
+      config:
+        personaPrefix: ''
+
+    # Agents created at startup. The base stays empty; raw overlays may create
+    # agents, while Web creates sessions on client request.
+    - id: agent-loop
+      name: '@qilin-agent/agent-loop'
+      config:
+        agents: []
+
+    # The sandboxed filesystem provider. `cwd` defaults to `process.cwd()`; an
+    # overlay can pin another workspace.
+    - id: fs-sandbox
+      name: '@qilin-agent/fs-sandbox'
+
+    # The native DeepSeek adapter. No key or endpoint is inlined: both resolve per
+    # request from the `llm-deepseek:` settings section over this entry, with the
+    # key coming from the credential store below. Thinking defaults are a deployment
+    # choice.
+    - id: llm-deepseek
+      name: '@qilin-agent/llm-deepseek-api-key'

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @qilin-agent/base — the shared qilin core as a profile bundle. The
+ * package's substance is `cordis.patch.yml`, declared by the `qilin.bundle.patch`
+ * manifest field and resolved by the profile composer through that field;
+ * this module carries no runtime API.
+ * @module @qilin-agent/base
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "@qilin-agent/base",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "The shared qilin core as a profile bundle: the first patch layer of base-backed profiles, inserting core rows over the empty profile root",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/bundle/base"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "qilin": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@qilin-agent/hmr": "3.1.3",
+    "@qilin-agent/kylin-plugin-timer": "~1.1.5",
+    "@qilin-agent/agent-default-model": "3.1.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/attachment-local": "3.1.3",
+    "@qilin-agent/agent-loop": "3.1.3",
+    "@qilin-agent/shell-env": "3.1.3",
+    "@qilin-agent/command-compact": "3.1.3",
+    "@qilin-agent/bash-sandbox": "3.1.3",
+    "@qilin-agent/command-feedback": "3.1.3",
+    "@qilin-agent/command-goal": "3.1.3",
+    "@qilin-agent/commands": "3.1.3",
+    "@qilin-agent/compaction-basic": "3.1.3",
+    "@qilin-agent/compaction-image-offload": "3.1.3",
+    "@qilin-agent/compaction-tool-result-pruner": "3.1.3",
+    "@qilin-agent/credentials-local": "3.1.3",
+    "@qilin-agent/deepseek-llm-api-extensions": "3.1.3",
+    "@qilin-agent/plugin-package-inventory-deepseek": "3.1.3",
+    "@qilin-agent/fs-observation-policy": "3.1.3",
+    "@qilin-agent/fs-sandbox": "3.1.3",
+    "@qilin-agent/goal": "3.1.3",
+    "@qilin-agent/goal-round-driver": "3.1.3",
+    "@qilin-agent/fs-local": "3.1.3",
+    "@qilin-agent/api-gateway": "3.1.3",
+    "@qilin-agent/llm-deepseek-api-key": "3.1.3",
+    "@qilin-agent/llm-pi-ai": "3.1.3",
+    "@qilin-agent/llm-retry": "3.1.3",
+    "@qilin-agent/permission-presets": "3.1.3",
+    "@qilin-agent/llm": "3.1.3",
+    "@qilin-agent/mcp-resources": "3.1.3",
+    "@qilin-agent/plan-mode": "3.1.3",
+    "@qilin-agent/pwsh-sandbox": "3.1.3",
+    "@qilin-agent/sandbox-local": "3.1.3",
+    "@qilin-agent/repeat-tool-reminder": "3.1.3",
+    "@qilin-agent/sandbox-policy": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/session-checkpoint-policy": "3.1.3",
+    "@qilin-agent/session-log-deepseek": "3.1.3",
+    "@qilin-agent/session-persistence-jsonl": "3.1.3",
+    "@qilin-agent/session-projection": "3.1.3",
+    "@qilin-agent/session-projection-cache": "3.1.3",
+    "@qilin-agent/session-query-sqlite": "3.1.3",
+    "@qilin-agent/session-telemetry-otel": "3.1.3",
+    "@qilin-agent/session-title": "3.1.3",
+    "@qilin-agent/skill": "3.1.3",
+    "@qilin-agent/skill-badge": "3.1.3",
+    "@qilin-agent/session-title-first-prompt-llm": "3.1.3",
+    "@qilin-agent/skill-filesystem": "3.1.3",
+    "@qilin-agent/settings-file": "3.1.3",
+    "@qilin-agent/spill-local": "3.1.3",
+    "@qilin-agent/spill-policy": "3.1.3",
+    "@qilin-agent/storage": "3.1.3",
+    "@qilin-agent/storage-json": "3.1.3",
+    "@qilin-agent/storage-domain": "3.1.3",
+    "@qilin-agent/subagent": "3.1.3",
+    "@qilin-agent/subagent-fork-in-process": "3.1.3",
+    "@qilin-agent/subprocess-local": "3.1.3",
+    "@qilin-agent/subagent-spawn-in-process": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/tool-call-timeout-policy": "3.1.3",
+    "@qilin-agent/token-meter": "3.1.3",
+    "@qilin-agent/tool-bash": "3.1.3",
+    "@qilin-agent/jobs-local": "3.1.3",
+    "@qilin-agent/tool-fs-search": "3.1.3",
+    "@qilin-agent/tool-present": "3.1.3",
+    "@qilin-agent/tool-goal": "3.1.3",
+    "@qilin-agent/tool-ralph": "3.1.3",
+    "@qilin-agent/tool-fs": "3.1.3",
+    "@qilin-agent/tool-pwsh": "3.1.3",
+    "@qilin-agent/tool-skill": "3.1.3",
+    "@qilin-agent/tool-schedule": "3.1.3",
+    "@qilin-agent/tool-subagent": "3.1.3",
+    "@qilin-agent/tool-subagent-control": "3.1.3",
+    "@qilin-agent/tool-jobs": "3.1.3",
+    "@qilin-agent/sidebar-opens": "3.1.3",
+    "@qilin-agent/tool-web": "3.1.3",
+    "@qilin-agent/typert-loader": "3.1.3",
+    "@qilin-agent/tool-workflow": "3.1.3",
+    "@qilin-agent/user-approval": "3.1.3",
+    "@qilin-agent/typert-registry": "3.1.3",
+    "@qilin-agent/tool-todo": "3.1.3",
+    "@qilin-agent/tools": "3.1.3",
+    "@qilin-agent/user-questions": "3.1.3",
+    "@qilin-agent/web": "3.1.3",
+    "@qilin-agent/web-fetch-http": "3.1.3",
+    "@qilin-agent/web-search-deepseek": "3.1.3",
+    "@qilin-agent/workflow-ptc": "3.1.3",
+    "@qilin-agent/agent-instructions": "3.1.3",
+    "@qilin-agent/plugin-manager": "3.1.3",
+    "@qilin-agent/ptc-runtime-node": "3.1.3",
+    "@qilin-agent/otel": "3.1.3"
+  },
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }