@qilin-agent/sdk-minimal 0.0.0-stage → 3.1.4

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,49 @@
+# 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/sdk-minimal/README.md
+/:
+  en: ae5bdac5add26503
+  zh: 93cd37d41c05fc9c
+/qilin-agent-sdk-minimal:
+  en: 981f63056421cbc4
+  zh: 02bab870cd4c4c4f
+/qilin-agent-sdk-minimal/summary:
+  en: 1bd3abec463eb574
+  zh: 8c314df925d7d077
+/qilin-agent-sdk-minimal/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-sdk-minimal/use-this-package:
+  en: 4812e6933c4644c1
+  zh: 622660b08d522558
+/qilin-agent-sdk-minimal/understand-the-implementation:
+  en: 39497164b317f6de
+  zh: 436dc8c8ea11e2d2
+/qilin-agent-sdk-minimal/understand-the-implementation/source-map:
+  en: 3784c554e96ab004
+  zh: 0a05d4fe1e26b3b1
+/qilin-agent-sdk-minimal/further-exploration:
+  en: 129d4391c4b8bc7f
+  zh: 7cd7e921fd3cb0c4
+/qilin-agent-sdk-minimal/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-sdk-minimal/model-experience/minimal-coding-agent-composition:
+  en: bd87e16b0c6e0506
+  zh: c8ee5e3b4578754e
+/qilin-agent-sdk-minimal/model-experience/minimal-coding-agent-composition/what-the-model-sees:
+  en: 35942c4229523952
+  zh: aafbf10057b5efb2
+/qilin-agent-sdk-minimal/model-experience/minimal-coding-agent-composition/token-effect:
+  en: 65613fb41fcc3151
+  zh: fc20a732aca8282c
+/qilin-agent-sdk-minimal/model-experience/minimal-coding-agent-composition/kv-cache-effect:
+  en: 904ae09b5fdb87c1
+  zh: de6fcaaa12bd9733
+/qilin-agent-sdk-minimal/known-limitations-and-deferred-work:
+  en: b30fe041e58923a0
+  zh: a081da02535d7fae
+/qilin-agent-sdk-minimal/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: e88aeb617ffb74ea

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+---
+description: "Standalone SDK profile with one default shell tool for users who need a minimal cross-platform coding agent without the shared base bundle."
+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/sdk-minimal`
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin --profile sdk-minimal` when an SDK client needs a small, explicit coding-agent runtime. By default, the profile advertises only a platform-selected persistent shell, persists sessions as uncompressed JSONL, and selects the model from the SDK initialization request. It supplies a complete Cordis tree and deliberately excludes `qilin-base`, Web, settings, managed credentials, telemetry, compaction, filesystem tools, workspace instructions, skills, jobs, and subagents. Its danger-full-access policy lets the shell modify any path available to the process, so use it only with an isolated workspace.
+
+## 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
+
+Launch the profile directly or select it from the Python SDK. Supply an explicit `QILIN_HOME`, use a disposable workspace, and provide the model credential through `DEEPSEEK_API_KEY`.
+
+```sh
+export QILIN_HOME=/absolute/path/to/example-qilin-home
+qilin --profile sdk-minimal
+```
+
+`QILIN_CONTEXT_WINDOW` sets the fallback capacity for a model absent from the adapter's advisory catalog. `QILIN_SYSTEM_PROMPT` replaces the default persona. The SDK initialization request is the sole model selection and overrides environment defaults.
+
+Use `qilin plugin --profile sdk-minimal` to manage persistent external dependencies. Profile, home, and ordered `--patch` files can replace rows or insert bundles above the complete default tree. The shipped template applies patches only at startup.
+
+The profile mounts exactly one persistent shell stack: Bash on Linux and macOS, or PowerShell on Windows. Both stacks use a 300-second timeout and one owner-scoped terminal; the other platform's rows remain disabled.
+
+Like every shipped profile, it mounts [MCP resources](../../mcp/mcp-resources/README.md) once. Configure only [MCP client entries](../../mcp/mcp-client/README.md) to add servers. Clients mounted by another provider also count as configured. With no server configured in the caller's scope, MCP contributes no prompt text or tools and the default remains one shell tool.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The bundle's single insert is the complete application tree: SDK stdio startup and JSON-RPC serving, one environment-configured DeepSeek adapter, the explicit agent core, conditional MCP resource tools, local subprocess execution, a platform-selected persistent shell PTY, and uncompressed JSONL persistence under `$QILIN_HOME/sessions`. It does not inherit another bundle, so every extra row is an explicit profile change.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | Complete standalone profile tree and its environment-backed defaults |
+| [`src/index.ts`](src/index.ts) | Bundle package entry |
+| [`tests/sdk-minimal.spec.ts`](tests/sdk-minimal.spec.ts) | Exact composition, profile-name, and platform-selection checks |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Python SDK example](../../../python/sdk/examples/README.md) — launches this profile from Python against an explicit Harness home.
+- [SDK application bundle](../sdk-app/README.md) — the JSON-RPC application layer reused by full and minimal SDK profiles.
+- [Base bundle](../base/README.md) — the full product foundation that this profile deliberately omits.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Minimal coding-agent composition
+
+#### What the model sees
+
+The system prompt is `QILIN_SYSTEM_PROMPT` or `You are a helpful software engineer assistant.`. With no MCP server configured, the only advertised tool is owner-scoped persistent `bash` on Linux/macOS or `pwsh` on Windows; runtime context, filesystem tools, workspace instructions, skills, jobs controls, compaction, and Harness identity are absent.
+
+#### Token effect
+
+By default, one stable persona plus one tool schema. Configured MCP servers add their tools, shared resource tools, and available server instructions. Tool results and ordinary conversation history grow with the session.
+
+#### KV Cache effect
+
+Stable for a fixed persona, platform, provider, model, and bundle patch stack. Profile changes take effect on the next process.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **The composition intentionally omits shared product services** — select `qilin --profile sdk` when settings, managed credentials, policy presets, telemetry, Web tools, or the full default tool roster are required.
+- **User patches can expand the tree and corrupt stdout** — profile customization is trusted application composition; a plugin that writes ordinary text to stdout can break JSON-RPC framing.
+
+<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,106 @@
+---
+description: "供需要不含共享 base bundle 的极简跨平台 coding agent（编程智能体）的用户使用的独立 SDK profile，默认提供一个 shell 工具。"
+kind: "package-bundle"
+---
+
+# `@qilin-agent/sdk-minimal`
+
+[English](README.md) | 中文
+
+## 概述
+
+当 SDK 客户端需要小型、显式的 coding agent 运行时时，请使用 `qilin --profile sdk-minimal`。该 profile 默认只公布按平台选择的持久 shell，把会话持久化为未压缩 JSONL，并从 SDK 初始化请求选择模型。它提供完整 Cordis 配置树，并刻意排除 `qilin-base`、Web、settings、托管凭据、遥测、压缩（compaction）、文件系统工具、workspace 指令、skill（技能）、jobs 与 subagent。其 danger-full-access 策略允许 shell 修改进程可访问的任何路径，因此只能配合隔离 workspace 使用。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+直接启动该 profile，或从 Python SDK 选择它。提供显式 `QILIN_HOME`、使用一次性 workspace，并通过 `DEEPSEEK_API_KEY` 提供模型凭据。
+
+```sh
+export QILIN_HOME=/absolute/path/to/example-qilin-home
+qilin --profile sdk-minimal
+```
+
+`QILIN_CONTEXT_WINDOW` 为不在适配器建议目录中的模型设置后备容量。`QILIN_SYSTEM_PROMPT` 替换默认 persona。SDK 初始化请求是唯一的模型选择依据，并覆盖环境默认值。
+
+使用 `qilin plugin --profile sdk-minimal` 管理持久外部依赖。Profile、home 与有序 `--patch` 文件可以替换完整默认配置树中的配置项，或在该配置树上方插入 bundle。随附模板只在启动时应用 patch。
+
+该 profile 只挂载一套持久 shell：Linux 和 macOS 使用 Bash，Windows 使用 PowerShell。两套配置都使用 300 秒超时与一个 agent 自有终端；另一平台的配置项保持禁用。
+
+与其他随附 profile 一样，它统一挂载 [MCP 资源](../../mcp/mcp-resources/README.zh.md)一次。只需配置 [MCP 客户端条目](../../mcp/mcp-client/README.zh.md)即可添加服务器。其他提供方挂载的客户端也属于已配置状态。调用方作用域中未配置服务器时，MCP 不贡献提示词文本或工具，默认仍只有一个 shell 工具。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+该 bundle 的单个 insert 就是完整应用配置树：SDK stdio 启动与 JSON-RPC 服务、一个由环境配置的 DeepSeek 适配器、显式 agent 核心、按配置启用的 MCP 资源工具、本地子进程执行、按平台选择的持久 shell PTY，以及位于 `$QILIN_HOME/sessions` 的未压缩 JSONL 持久化。它不继承其他 bundle，因此每个额外配置项都是显式 profile 变更。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`cordis.patch.yml`](cordis.patch.yml) | 完整独立 profile 配置树及其环境默认值 |
+| [`src/index.ts`](src/index.ts) | Bundle 包入口 |
+| [`tests/sdk-minimal.spec.ts`](tests/sdk-minimal.spec.ts) | 精确组合、profile 名称与平台选择检查 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Python SDK 示例](../../../python/sdk/examples/README.zh.md)——从 Python 启动本 profile，并使用明确指定的 Harness home。
+- [SDK 应用 bundle](../sdk-app/README.zh.md)——完整与极简 SDK profile 复用的 JSON-RPC 应用层。
+- [Base bundle](../base/README.zh.md)——本 profile 刻意省略的完整产品基础。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 极简 coding agent 组合
+
+#### 模型看到的内容
+
+系统提示词取 `QILIN_SYSTEM_PROMPT`，未设置时使用 `You are a helpful software engineer assistant.`。未配置 MCP 服务器时，对外公布的唯一工具是 Linux/macOS 上 agent 所有的持久 `bash` 或 Windows 上的 `pwsh`；运行时上下文、文件系统工具、workspace 指令、skill、jobs 控制、压缩与 Harness 身份均不存在。
+
+#### Token 影响
+
+默认是一个稳定 persona 加一个工具 schema。已配置 MCP 服务器会添加自己的工具、共享资源工具及可用的服务器指令。工具结果与普通对话历史随会话增长。
+
+#### KV Cache 影响
+
+当 persona、平台、提供方、模型与 bundle patch 栈固定时保持稳定。Profile 变更在下一个进程生效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **该组合刻意省略共享产品服务** — 需要 settings、托管凭据、策略预设、遥测、Web 工具或完整默认工具清单时，请选择 `qilin --profile sdk`。
+- **用户 patch 可以扩展配置树并破坏 stdout** — profile 自定义属于受信任的应用组合；向 stdout 写入普通文本的插件会破坏 JSON-RPC 分帧。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/cordis.patch.yml

@@ -0,0 +1,143 @@
+# Standalone minimal SDK application. Unlike the ordinary SDK profile, this
+# bundle does not layer over qilin-base: this insert is the complete Cordis tree.
+# User profile, home, and invocation patches still apply above it.
+
+- insert:
+    - id: sdk-app-startup
+      name: '@qilin-agent/sdk-app'
+      config:
+        profile: sdk-minimal
+
+    - id: sdk-jsonrpc-server
+      name: '@qilin-agent/sdk-jsonrpc-server'
+      inject: [sdkAppStartup, loader]
+      config:
+        maxTokensAsSuccess: false
+
+    - id: deepseek-llm-api-extensions
+      name: '@qilin-agent/deepseek-llm-api-extensions'
+
+    - id: session-log-deepseek
+      name: '@qilin-agent/session-log-deepseek'
+
+    - id: plugin-package-inventory-deepseek
+      name: '@qilin-agent/plugin-package-inventory-deepseek'
+
+    - id: llm-deepseek
+      name: '@qilin-agent/llm-deepseek-api-key'
+      config:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        defaultContextWindow: !!js Number(process.env.QILIN_CONTEXT_WINDOW ?? 1000000)
+        streamIdleTimeoutMs: 172800000
+
+    - id: sandbox
+      name: '@qilin-agent/sandbox-local'
+
+    # Shared projection registry: sandbox-policy and terminal-bash fold
+    # sandbox-mode state through its units and require it as a hard injection.
+    - id: session-projection
+      name: '@qilin-agent/session-projection'
+
+    - id: sandbox-policy
+      name: '@qilin-agent/sandbox-policy'
+      config:
+        mode: danger-full-access
+        workspaceRoot: !!js process.cwd()
+
+    - id: subprocess
+      name: '@qilin-agent/subprocess-local'
+
+    - id: pty
+      name: '@qilin-agent/terminal'
+
+    - id: terminal-bash
+      name: '@qilin-agent/terminal-bash'
+      disabled: !!js process.platform === 'win32'
+      config:
+        timeoutMs: 300000
+
+    - id: terminal-pwsh
+      name: '@qilin-agent/terminal-bash'
+      disabled: !!js process.platform !== 'win32'
+      config:
+        shellDialect: pwsh
+        timeoutMs: 300000
+
+    # Keep the minimal agent kernel explicit: unlike qilin-base, this profile
+    # owns each service row and omits every optional producer it does not use.
+    - id: timer
+      name: '@qilin-agent/kylin-plugin-timer'
+
+    - id: llm
+      name: '@qilin-agent/llm'
+
+    - id: session
+      name: '@qilin-agent/session'
+
+    - id: session-title
+      name: '@qilin-agent/session-title'
+      config:
+        fallbackMaxWords: 5
+        fallbackMaxBytes: 40
+        maxTitleBytes: 80
+
+    - id: system-prompt
+      name: '@qilin-agent/system-prompt'
+      config:
+        includeHarnessIdentity: false
+        includeRuntimeContext: false
+        personaPrefix: !!js process.env.QILIN_SYSTEM_PROMPT ?? 'You are a helpful software engineer assistant.'
+
+    - id: tools
+      name: '@qilin-agent/tools'
+
+    - id: mcp-resources
+      name: '@qilin-agent/mcp-resources'
+
+    - id: agent
+      name: '@qilin-agent/agent'
+
+    - id: llm-retry
+      name: '@qilin-agent/llm-retry'
+
+    - id: jobs
+      name: '@qilin-agent/jobs-local'
+
+    - id: agent-loop
+      name: '@qilin-agent/agent-loop'
+      config:
+        agents: []
+
+    - id: persistent-bash
+      name: '@qilin-agent/tool-bash-persistent'
+      disabled: !!js process.platform === 'win32'
+      config:
+        timeoutMs: 300000
+        description: |-
+          Run commands in a bash shell
+          * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+          * Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.
+          * State is persistent across command calls and discussions with the user.
+          * To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.
+          * Please avoid commands that may produce a very large amount of output.
+          * Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.
+
+    - id: persistent-pwsh
+      name: '@qilin-agent/tool-pwsh-persistent'
+      disabled: !!js process.platform !== 'win32'
+      config:
+        timeoutMs: 300000
+        description: |-
+          Run commands in a PowerShell shell
+          * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+          * You don't have access to the internet via this tool.
+          * State is persistent across command calls and discussions with the user.
+          * Use native Windows paths (C:\...) and $env:NAME variables; this is PowerShell, not bash.
+          * Please avoid commands that may produce a very large amount of output.
+          * Please run long lived commands in the background, e.g. 'Start-Job' or start a server with Start-Process.
+
+    - id: sessions
+      name: '@qilin-agent/session-persistence-jsonl'
+      config:
+        root: !!js qilinHomePath('sessions')
+        compression: none

package/lib/index.js

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

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @qilin-agent/sdk-minimal — the standalone minimal SDK profile bundle.
+ * The package's substance is `cordis.patch.yml`, declared by the
+ * `qilin.bundle.patch` manifest field and resolved by the profile composer;
+ * this module carries no runtime interface.
+ * @module @qilin-agent/sdk-minimal
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@qilin-agent/sdk-minimal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "The standalone minimal SDK profile bundle: JSON-RPC, one DeepSeek adapter, persistent shell, and JSONL sessions",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/bundle/sdk-minimal"
+  },
+  "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/agent": "3.1.4",
+    "@qilin-agent/kylin-plugin-timer": "~1.1.5",
+    "@qilin-agent/agent-loop": "3.1.4",
+    "@qilin-agent/deepseek-llm-api-extensions": "3.1.4",
+    "@qilin-agent/jobs-local": "3.1.4",
+    "@qilin-agent/llm-deepseek-api-key": "3.1.4",
+    "@qilin-agent/llm-retry": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/mcp-resources": "3.1.4",
+    "@qilin-agent/plugin-package-inventory-deepseek": "3.1.4",
+    "@qilin-agent/sdk-app": "3.1.4",
+    "@qilin-agent/sandbox-policy": "3.1.4",
+    "@qilin-agent/sdk-jsonrpc-server": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/session-persistence-jsonl": "3.1.4",
+    "@qilin-agent/session-log-deepseek": "3.1.4",
+    "@qilin-agent/session-title": "3.1.4",
+    "@qilin-agent/sandbox-local": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/terminal": "3.1.4",
+    "@qilin-agent/subprocess-local": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/terminal-bash": "3.1.4",
+    "@qilin-agent/tools": "3.1.4",
+    "@qilin-agent/tool-bash-persistent": "3.1.4",
+    "@qilin-agent/tool-pwsh-persistent": "3.1.4"
+  },
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }