@qilin-agent/ptc-runtime 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,70 @@
+# 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/ptc-runtime/ptc-runtime/README.md
+/:
+  en: 8904d5f5d5251a83
+  zh: 69b48f289b0416f0
+/qilin-ptc-runtime:
+  en: d42ce906e041d70f
+  zh: e79dad767dc088fa
+/qilin-ptc-runtime/summary:
+  en: aa7a516fb2d2aa4e
+  zh: 376b1643a609cfcc
+/qilin-ptc-runtime/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-ptc-runtime/use-this-package:
+  en: d44e65c8661b730f
+  zh: 9c77a9f84eb0bbea
+/qilin-ptc-runtime/use-this-package/run-a-program:
+  en: 6f97019cebc2f417
+  zh: c56f18a690dbe814
+/qilin-ptc-runtime/use-this-package/choose-a-backend:
+  en: a5003c50fdc3d4a2
+  zh: ff515f42f2190595
+/qilin-ptc-runtime/use-this-package/name-your-bindings-portably:
+  en: 4e46c1672701b8df
+  zh: 0353c5855c9ff6be
+/qilin-ptc-runtime/use-this-package/what-can-go-wrong:
+  en: 44f9fdf2c8e2cacc
+  zh: 99dd555a49075f88
+/qilin-ptc-runtime/understand-the-implementation:
+  en: 686d570f5e669fa4
+  zh: 2075cf27c30f251a
+/qilin-ptc-runtime/understand-the-implementation/design-concept:
+  en: 431cb865534531fd
+  zh: c8657a788cd7f548
+/qilin-ptc-runtime/understand-the-implementation/service-api:
+  en: 30e9c684936d592e
+  zh: ac0a5ffc90aa39a8
+/qilin-ptc-runtime/understand-the-implementation/vocabulary:
+  en: 855cb8366e3bd293
+  zh: da6d7a0ce51f97fc
+/qilin-ptc-runtime/understand-the-implementation/portable-identifiers:
+  en: 77cb0cf02489d96e
+  zh: 7bbf502ee570911c
+/qilin-ptc-runtime/understand-the-implementation/source-map:
+  en: 85b65ceb9be0c49f
+  zh: 52df7f06d4e49d6e
+/qilin-ptc-runtime/further-exploration:
+  en: 35820f1d5fd01020
+  zh: 5cc8f5aab55bcc93
+/qilin-ptc-runtime/model-experience:
+  en: d892ff107f13572b
+  zh: 162a6d64de2eee23
+/qilin-ptc-runtime/model-experience/kv-cache-effect:
+  en: 40294c1c31b74824
+  zh: 081cebc2e2650f03
+/qilin-ptc-runtime/known-limitations-and-deferred-work:
+  en: 7f30f78c5d427667
+  zh: 99d21160016deea2
+/qilin-ptc-runtime/known-limitations-and-deferred-work/dev-note:
+  en: d56846da29ad869c
+  zh: 0397151a7e29b8ba
+/qilin-ptc-runtime/known-limitations-and-deferred-work/dev-note/future-persistent-kernel-backend:
+  en: cfefaae6ed9705d5
+  zh: 3cca5b1bd92445b0
+/qilin-ptc-runtime/known-limitations-and-deferred-work/dev-note/future-container-backend:
+  en: 2b94202842f0556c
+  zh: 5aa0311fa621a018

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+---
+description: "Abstract PTC execution seam (`ctx.ptcRuntime`) for users and maintainers composing, consuming, or building a backend that runs one model-written program against host-provided bindings."
+kind: "package-reference"
+---
 
-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/ptc-runtime
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-ptc-runtime` to run one model-written program against host-provided asynchronous functions through a configured backend. A request returns a lossless-JSON value, ordered per-channel logs, or a structured error; program failures resolve in the result, while rejected promises indicate caller misuse. Each run is isolated from prior runs, and the runtime has no knowledge of tools or sessions. Choose an execution backend separately; its language and isolation descriptors identify the required source language and execution substrate but do not themselves promise a security boundary.
+
+## 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
+
+Choose this package when you compose a deployment that executes model-written programs, consume `ctx.ptcRuntime` directly, or build a backend that runs programs. PTC mode in `qilin-tools` uses it for tool programs, and `qilin-workflow-ptc` uses it for workflow orchestration. Each consumer owns the content returned to its model.
+
+### Run a program
+
+Give the runtime a program and binding namespaces, then call `resolve(request)` followed by `run(spec)`. Resolution validates optional cwd, timeout and sandbox policy against the provider's capabilities and fills deployment defaults. The program runs as an async function body, so top-level `await` and `return` work; a lossless-JSON completion becomes `result.value`, captured text becomes `result.logs`, and program failures become `result.error`. Each output channel preserves its own order, while cross-channel interleaving is backend-dependent.
+
+```text
+const spec = ctx.ptcRuntime.resolve({
+  program: 'return await tools.add({ a: 1, b: 2 })',
+  bindings: [{ global: 'tools', functions: { add: async (args) => args.a + args.b } }],
+})
+const result = await ctx.ptcRuntime.run(spec)
+// result.value === 3
+```
+
+### Choose a backend
+
+Backends expose `language` and `isolation` as diagnostic descriptors; neither grants authority or proves confinement. [`qilin-ptc-runtime-node`](../ptc-runtime-node/README.md) executes erasable TypeScript in a fresh managed Node process under the resolved sandbox policy. The private [`qilin-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.md) provider executes Python in a fresh CPython subprocess without file confinement. `sandboxMode` advertises a provider's deployment file-policy mode, or is absent when that capability is unsupported.
+
+### Name your bindings portably
+
+Binding-global and error-class names are language-portable: they must match `[A-Za-z_][A-Za-z0-9_]*`, avoid every portable target language's reserved words, and avoid backend-owned slots, so one namespace list is valid against every backend. A name like `$tools`, `lambda`, or `console` fails the run before it starts; the exact exclusion sets are part of the seam contract.
+
+### What can go wrong
+
+Failures arrive as `result.error` with an orthogonal `kind`: `exception`, `timeout`, `abort`, `worker-exit`, `invalid-output`, `output-limit`, `protocol` or `sandbox-unavailable`. Providers return applicable `result.sandbox` facts separately from success or failure. Invalid or unsupported execution options fail during `resolve`; `run` rejects caller misuse, such as unresolved inputs, invalid binding names or a call after disposal.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the seam; observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The package is the Service Definition role of the PTC execution capability seam ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract `PtcRuntime extends Service` registered as `ctx.ptcRuntime`, plus the vocabulary providers and consumers share. Providers subclass `PtcRuntime`, implement `resolve` and `run`, and register the service. PTC mode in `qilin-tools` owns tool bindings, while `qilin-workflow-ptc` owns workflow hooks and child agents. The runtime stays ignorant of tools and sessions by contract: it receives a program, named async bindings and resolved execution options, then returns captured output, the outcome and applicable sandbox facts.
+
+### Service API
+
+The readonly `timeout` descriptor exposes numeric `{ defaultMs, maxMs }` for consumer presentation; an absent descriptor means numeric overrides are unsupported. An omitted `timeoutMs` selects the provider default; a number requests a validated, capped elapsed budget; explicit `null` requests no elapsed deadline. A provider rejects choices it does not support. The Node workflow adapter requests `null`, while the model-facing `run_code` tool accepts only positive numeric overrides.
+
+`executionInstructions` supplies provider-owned usage guidance, or an empty string when none is needed. Consumers can include it in their program presentation without identifying the provider from its language or isolation descriptor; PTC includes it in the logged `run_code` schema.
+
+`resolve(request)` owns supported option validation and deployment defaulting. `run(spec)` executes the complete inputs and resolves program outcomes after cleanup. Language and substrate descriptors guide presentation; `sandboxMode` indicates whether the consumer can pass a resolved file policy. Neither descriptors nor a successful program result substitute for the backend's reported enforcement facts.
+
+The exhaustive semantics live in the [PTC runtime subsystem reference](../../../docs/subsystems/ptc-runtime.md); the exact signatures are in [`src/index.ts`](src/index.ts).
+
+### Vocabulary
+
+`PtcRunRequest` carries the program, host bindings, cancellation and optional execution choices. `PtcRunSpec` requires the resolved cwd and an explicit numeric or null deadline choice. `PtcBindingNamespace` declares program globals and optional typed rejection constructors. `PtcRunResult` separates logs/value, failure and `PtcRunSandbox` facts; exact fields and provider obligations live in [`src/types.ts`](src/types.ts).
+
+### Portable identifiers
+
+Binding-global and error-class names are language-portable: they must match the identifier subset `[A-Za-z_][A-Za-z0-9_]*` (no JS-only `$`) and clear the seam-exported exclusion sets, so one `bindings` list is valid against every backend. The package exports the contract every backend enforces — `PORTABLE_RESERVED_WORDS` (ECMAScript ∪ Python reserved words), `RESERVED_BINDING_GLOBALS` (backend-owned globals such as `console` and `__qilin_main__`), `RESERVED_ERROR_MEMBERS` and `DUNDER_MEMBER` (error-member exclusions) — so a name like `$tools`, `lambda`, or `__qilin_main__` makes `run()` reject as seam misuse on any backend. See `src/index.ts` for the exact sets.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: abstract `PtcRuntime` service and the portable-identifier exclusion sets |
+| [`src/types.ts`](src/types.ts) | Vocabulary: `PtcRunRequest`, `PtcRunSpec`, bindings, results, failures and sandbox facts |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these when the package-level contract is not enough. They move from the PTC mode consumer to the backends and the capability-seam model.
+
+- [PTC mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-ptc.md) — how the tool registry consumes `ctx.ptcRuntime` and presents `run_code` to the model.
+- [Node process backend](../ptc-runtime-node/README.md) — the shipped TypeScript execution backend.
+- [Experimental Python backend](../../experimental/ptc-runtime-python/README.md) — the private CPython subprocess provider and its fd-3 protocol.
+- [PTC runtime subsystem reference](../../../docs/subsystems/ptc-runtime.md) — request/result vocabulary, bindings, and the `ctx.ptcRuntime` cordis surface.
+- [Capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) — the Service Definition / Service Provider / Consumer split.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through PTC mode in `qilin-tools` and the workflow adapter, which present program outcomes through their own tool results.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the seam cannot do; they are current package constraints, not a task backlog.
+
+- **`run()` is one-shot** — `logs` arrive only on the resolved `PtcRunResult`; the seam exposes no streaming-log or progress API for a live program's output.
+- **No state survives between runs** — every request runs against a fresh world; a persistent REPL-style kernel is deferred until a backend brings its own logging story.
+- **Providers have different confinement capabilities** — the shipped Node provider enforces a resolved file policy, while the private experimental Python provider rejects an explicit policy. No container provider is supplied.
+- **No uniform binding byte cap applies across providers** — each provider owns its transport limits; a binding can still allocate memory before its result reaches those limits.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: undecided directions and open questions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and the package code.
+
+#### Future: persistent kernel backend
+
+A REPL-style kernel that keeps state across `run_code` calls remains undecided; it would need its own logging story, because the no-state-between-runs contract is what keeps every request reconstructable from the session log alone.
+
+#### Future: container backend
+
+A container-class backend would provide a hard multi-tenant boundary for both code and shell execution; nothing is decided beyond the well-known `isolation` value.
+
+</details>

package/README.zh.md

@@ -0,0 +1,148 @@
+---
+description: "抽象 PTC 执行 seam（`ctx.ptcRuntime`），供用户与维护者组合、消费或构建后端，以针对宿主提供的绑定运行一段模型编写的程序。"
+kind: "package-reference"
+---
+
+# @qilin-agent/ptc-runtime
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `qilin-ptc-runtime`，可通过已配置的后端，针对宿主提供的异步函数运行一段模型编写的程序。请求返回无损 JSON 值、通道内有序的日志或结构化错误；程序失败在结果中 resolve，而 Promise reject 表示调用方误用。每次运行都与先前运行隔离，且运行时不了解工具或会话。执行后端需另行选择；其语言与隔离描述符标明所需的源语言和执行基底，但这些描述符本身不承诺安全边界。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当你要组合一个执行模型程序的部署、直接消费 `ctx.ptcRuntime`，或构建运行程序的后端时，选择本包。`qilin-tools` 中的 PTC mode 用它执行工具程序，`qilin-workflow-ptc` 用它编排工作流。每个消费方负责返回给模型的内容。
+
+### 运行一个程序
+
+向运行时提供程序与绑定命名空间，然后依次调用 `resolve(request)` 和 `run(spec)`。解析根据提供方能力验证可选 cwd、timeout 与沙箱策略，并填入部署默认值。程序作为异步函数体运行，支持顶层 `await` 与 `return`；无损 JSON 完成值成为 `result.value`，捕获文本成为 `result.logs`，程序失败成为 `result.error`。每个输出通道保持自身顺序，跨通道交错由后端决定。
+
+```text
+const spec = ctx.ptcRuntime.resolve({
+  program: 'return await tools.add({ a: 1, b: 2 })',
+  bindings: [{ global: 'tools', functions: { add: async (args) => args.a + args.b } }],
+})
+const result = await ctx.ptcRuntime.run(spec)
+// result.value === 3
+```
+
+### 选择后端
+
+后端以 `language` 与 `isolation` 提供诊断描述符；两者都不授予权限或证明约束。[`qilin-ptc-runtime-node`](../ptc-runtime-node/README.zh.md) 在全新的受管 Node 进程中按已解析沙箱策略执行可擦除 TypeScript。私有的 [`qilin-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.zh.md) 提供方在全新 CPython 子进程中执行 Python，不提供文件约束。`sandboxMode` 声明提供方的部署文件策略模式；不支持该能力时则缺省。
+
+### 可移植地命名绑定
+
+binding-global 与 error-class 名称是语言可移植的：必须匹配 `[A-Za-z_][A-Za-z0-9_]*`，避开每个可移植目标语言的保留字，并避开后端拥有的槽位，因此同一份命名空间列表对每个后端都有效。`$tools`、`lambda` 或 `console` 之类的名称会在运行开始前失败；确切的排除集是 seam 约定的一部分。
+
+### 可能出什么问题
+
+失败以 `result.error` 返回，带正交的 `kind`：`exception`、`timeout`、`abort`、`worker-exit`、`invalid-output`、`output-limit`、`protocol` 或 `sandbox-unavailable`。提供方在成功或失败之外，单独返回适用的 `result.sandbox` 事实。无效或不支持的执行选项在 `resolve` 期间失败；`run` 拒绝调用方误用，例如未解析输入、无效绑定名或资源释放后的调用。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释 seam 背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+本包是 PTC 执行能力 seam 的 Service Definition 角色（[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)）：一个注册为 `ctx.ptcRuntime` 的抽象 `PtcRuntime extends Service`，加上提供方与消费方共享的词汇。提供方继承 `PtcRuntime`、实现 `resolve` 和 `run` 并注册服务。`qilin-tools` 中的 PTC mode 负责工具绑定，`qilin-workflow-ptc` 负责工作流钩子与子 agent。按约定，运行时不了解工具与会话：它接收程序、具名异步绑定和已解析执行选项，然后返回捕获输出、执行结果与适用的沙箱事实。
+
+### 服务 API
+
+只读 `timeout` 描述符公开数值型 `{ defaultMs, maxMs }`，供消费方呈现；描述符缺省表示不支持数值覆盖。省略 `timeoutMs` 使用提供方默认值；数值请求经过验证和封顶的经过时间预算；显式 `null` 请求不设经过时间截止。提供方拒绝不支持的选择。Node 工作流适配器请求 `null`，而面向模型的 `run_code` 工具只接受正数覆盖值。
+
+`executionInstructions` 提供由运行时拥有的使用说明；不需要说明时返回空字符串。消费方可将其纳入程序呈现，无需根据语言或隔离描述符识别提供方；PTC 将它纳入已记录的 `run_code` schema。
+
+`resolve(request)` 负责支持选项的验证与部署默认值。`run(spec)` 执行完整输入，并在清理后返回程序结果。语言和执行基底描述符指导呈现；`sandboxMode` 表示消费方能否传入已解析文件策略。描述符与程序成功结果都不能代替后端报告的强制能力事实。
+
+穷尽式语义见[PTC 运行时子系统参考](../../../docs/subsystems/ptc-runtime.zh.md)；确切签名见 [`src/index.ts`](src/index.ts)。
+
+### 词汇
+
+`PtcRunRequest` 携带程序、Host 绑定、取消和可选执行选择。`PtcRunSpec` 要求已解析的 cwd 和明确的数值或 null 截止选择。`PtcBindingNamespace` 声明程序全局对象与可选的类型化拒绝构造器。`PtcRunResult` 将日志／值、失败与 `PtcRunSandbox` 事实分开；确切字段与提供方义务见 [`src/types.ts`](src/types.ts)。
+
+### 可移植标识符
+
+binding-global 与 error-class 名称是语言可移植的：必须匹配标识符子集 `[A-Za-z_][A-Za-z0-9_]*`（不含 JS 专有的 `$`）并通过 seam 导出的排除集，因此同一份 `bindings` 列表对每个后端都有效。本包导出每个后端都执行的约定——`PORTABLE_RESERVED_WORDS`（ECMAScript ∪ Python 保留字）、`RESERVED_BINDING_GLOBALS`（如 `console`、`__qilin_main__` 等后端拥有的 global）、`RESERVED_ERROR_MEMBERS` 与 `DUNDER_MEMBER`（error-member 排除）——因此 `$tools`、`lambda` 或 `__qilin_main__` 之类的名称会让 `run()` 在任何后端上作为 seam 误用而 reject。确切集合见 `src/index.ts`。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `PtcRuntime` 服务与可移植标识符排除集 |
+| [`src/types.ts`](src/types.ts) | 词汇：`PtcRunRequest`、`PtcRunSpec`、绑定、结果、失败与沙箱事实 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下内容。它们从 PTC mode 消费方进入后端与能力 seam 模型。
+
+- [PTC mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md)——工具注册表如何消费 `ctx.ptcRuntime` 并把 `run_code` 呈现给模型。
+- [Node 进程后端](../ptc-runtime-node/README.zh.md)——已发布的 TypeScript 执行后端。
+- [实验性 Python 后端](../../experimental/ptc-runtime-python/README.zh.md)——私有的 CPython 子进程提供方及其 fd-3 协议。
+- [PTC 运行时子系统参考](../../../docs/subsystems/ptc-runtime.zh.md)——请求／结果词汇、绑定与 `ctx.ptcRuntime` 的 cordis 接口面。
+- [能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)——Service Definition / Service Provider / Consumer 拆分。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+通过 `qilin-tools` 中的 PTC mode 与工作流适配器间接提供；它们通过各自的工具结果呈现程序结果。
+
+#### KV Cache 影响
+
+不会直接失效；由上述消费方负责请求前缀变更。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明 seam 不能做什么；它们是当前包约束，不是任务积压。
+
+- **`run()` 是一次性的**——`logs` 只有在 `PtcRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
+- **运行之间不保留状态**——每次请求都在全新环境中运行；持久 REPL 风格内核在某个后端带来自己的日志方案之前保持延期。
+- **提供方的约束能力不同**——已发布 Node 提供方强制执行已解析文件策略，私有实验性 Python 提供方拒绝显式策略。不提供容器提供方。
+- **提供方之间没有统一的绑定字节上限**——各提供方负责自己的传输限制；绑定仍可能在结果到达这些限制前分配内存。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：尚未决定的方向与开放问题。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
+
+#### 未来：持久内核后端
+
+跨 `run_code` 调用保留状态的 REPL 风格内核仍未决定；它需要自己的日志方案，因为「运行之间不保留状态」的约定正是让每次请求仅凭会话日志即可重建的原因。
+
+#### 未来：容器后端
+
+容器级后端将为代码与 shell 执行都提供硬性的多租户边界；除已知的 `isolation` 值外，暂无任何决定。
+
+</details>

package/lib/index.js

@@ -0,0 +1,161 @@
+import { Service } from "@qilin-agent/kylin";
+//#region lib/types/index.js
+/**
+* Service Definition for the PTC execution capability seam that runs one model-written program against host async bindings.
+* Runtimes know nothing about tools or sessions; consumers own those concerns.
+* @module @qilin-agent/ptc-runtime
+*/
+/**
+* Binding globals EVERY backend refuses because SOME backend owns the slot in
+* the program's namespace: `console` (Node's log capture), and
+* `__qilin_main__`/`__builtins__`/`__name__` (the Python backend's bootstrap
+* wrapper and seeded module globals),
+* and `__debug__`. One shared set — rather than each backend refusing only its
+* own slots — keeps the portability promise real: a namespace list valid on
+* one backend is valid on all, so a caller cannot pick a name that works on
+* Node and collides on Python (or vice versa). `__name__` et al. ARE
+* valid portable identifiers, so the identifier rule on
+* `PtcBindingNamespace.global` never rejects them — hence this explicit set.
+* (Error members differ: {@link DUNDER_MEMBER} refuses every dunder form
+* wholesale; binding globals refuse only the names listed here.) `__debug__`
+* is listed for a different reason than a collision: CPython compiles a bare
+* `__debug__` reference to the constant `True` and rejects any assignment to
+* the name at COMPILE time, so an injected global under that name is
+* unreachable from the program — accepted by validation, unusable on the
+* Python backend, which is exactly the split the shared set exists to prevent.
+*/
+const RESERVED_BINDING_GLOBALS = new Set([
+	"console",
+	"__qilin_main__",
+	"__builtins__",
+	"__name__",
+	"__debug__"
+]);
+/**
+* `PtcBindingErrorClass.memberNameProperty` names EVERY backend refuses, as
+* one shared contract so a request valid on one backend is valid on all. The
+* JS `Error` exclusions (`name`, `message`, `stack`) and Python's
+* exception-protocol members (`args`, `with_traceback`, `add_note`) are
+* listed by name; dunder-form names (`__x__`, non-empty middle) are refused
+* wholesale — several are constrained CPython descriptors whose `setattr`
+* raises while constructing the rejection, and the exact set is an interpreter
+* version detail. Any other non-empty own property name is accepted everywhere.
+*/
+const RESERVED_ERROR_MEMBERS = new Set([
+	"name",
+	"message",
+	"stack",
+	"args",
+	"with_traceback",
+	"add_note"
+]);
+/**
+* Dunder form (`__x__`, non-empty middle): object-protocol slots in Python,
+* refused as {@link RESERVED_ERROR_MEMBERS | error members} on every backend.
+*/
+const DUNDER_MEMBER = /^__.+__$/;
+/**
+* Reserved words of every portable target language (ECMAScript ∪ Python),
+* refused as {@link PtcBindingNamespace.global} / error-class names by all
+* backends, one per language: the released TypeScript Node process and the
+* experimental, private CPython subprocess. The portable-identifier contract
+* promises a namespace list valid on one backend is valid on every backend; a
+* per-language check would let `lambda` pass the TypeScript backend and fail
+* the Python one. Extending the seam with a new language means widening this
+* union (a breaking review of existing binding names, by design).
+*/
+const PORTABLE_RESERVED_WORDS = new Set([
+	"await",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"function",
+	"if",
+	"import",
+	"in",
+	"instanceof",
+	"new",
+	"null",
+	"return",
+	"super",
+	"switch",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield",
+	"let",
+	"static",
+	"implements",
+	"interface",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"arguments",
+	"eval",
+	"False",
+	"None",
+	"True",
+	"and",
+	"as",
+	"assert",
+	"async",
+	"def",
+	"del",
+	"elif",
+	"except",
+	"from",
+	"global",
+	"is",
+	"lambda",
+	"nonlocal",
+	"not",
+	"or",
+	"pass",
+	"raise",
+	"match",
+	"type",
+	"_"
+]);
+/**
+* Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
+* failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
+* structured-cloneable bindings, materialize each declared namespace rejection
+* class, treat programs as hostile peers, isolate runs from one another, and
+* terminate and await in-flight runs during disposal.
+*/
+var PtcRuntime = class extends Service {
+	/** Provider-owned program usage guidance for consumers to present alongside the source language. */
+	get executionInstructions() {
+		return "";
+	}
+	/** Deployment file-policy mode, or undefined for a provider without confinement support. */
+	get sandboxMode() {}
+	/** Configured numeric elapsed-time defaults and cap, or undefined when per-call overrides are unsupported. */
+	get timeout() {}
+	constructor(ctx) {
+		super(ctx, "ptcRuntime");
+	}
+};
+//#endregion
+export { DUNDER_MEMBER, PORTABLE_RESERVED_WORDS, PtcRuntime, PtcRuntime as default, RESERVED_BINDING_GLOBALS, RESERVED_ERROR_MEMBERS };

package/lib/types/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Service Definition for the PTC execution capability seam that runs one model-written program against host async bindings.
+ * Runtimes know nothing about tools or sessions; consumers own those concerns.
+ * @module @qilin-agent/ptc-runtime
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { PtcRunRequest, PtcRunResult, PtcRunSpec } from './types.ts';
+import type { SandboxMode } from '@qilin-agent/sandbox';
+export type { PtcBindingErrorClass, PtcBindingFunction, PtcBindingNamespace, PtcJsonValue, PtcRunFailure, PtcRunRequest, PtcRunResult, PtcRunSpec, PtcRunSandbox, } from './types.ts';
+/**
+ * Binding globals EVERY backend refuses because SOME backend owns the slot in
+ * the program's namespace: `console` (Node's log capture), and
+ * `__qilin_main__`/`__builtins__`/`__name__` (the Python backend's bootstrap
+ * wrapper and seeded module globals),
+ * and `__debug__`. One shared set — rather than each backend refusing only its
+ * own slots — keeps the portability promise real: a namespace list valid on
+ * one backend is valid on all, so a caller cannot pick a name that works on
+ * Node and collides on Python (or vice versa). `__name__` et al. ARE
+ * valid portable identifiers, so the identifier rule on
+ * `PtcBindingNamespace.global` never rejects them — hence this explicit set.
+ * (Error members differ: {@link DUNDER_MEMBER} refuses every dunder form
+ * wholesale; binding globals refuse only the names listed here.) `__debug__`
+ * is listed for a different reason than a collision: CPython compiles a bare
+ * `__debug__` reference to the constant `True` and rejects any assignment to
+ * the name at COMPILE time, so an injected global under that name is
+ * unreachable from the program — accepted by validation, unusable on the
+ * Python backend, which is exactly the split the shared set exists to prevent.
+ */
+export declare const RESERVED_BINDING_GLOBALS: ReadonlySet<string>;
+/**
+ * `PtcBindingErrorClass.memberNameProperty` names EVERY backend refuses, as
+ * one shared contract so a request valid on one backend is valid on all. The
+ * JS `Error` exclusions (`name`, `message`, `stack`) and Python's
+ * exception-protocol members (`args`, `with_traceback`, `add_note`) are
+ * listed by name; dunder-form names (`__x__`, non-empty middle) are refused
+ * wholesale — several are constrained CPython descriptors whose `setattr`
+ * raises while constructing the rejection, and the exact set is an interpreter
+ * version detail. Any other non-empty own property name is accepted everywhere.
+ */
+export declare const RESERVED_ERROR_MEMBERS: ReadonlySet<string>;
+/**
+ * Dunder form (`__x__`, non-empty middle): object-protocol slots in Python,
+ * refused as {@link RESERVED_ERROR_MEMBERS | error members} on every backend.
+ */
+export declare const DUNDER_MEMBER: RegExp;
+/**
+ * Reserved words of every portable target language (ECMAScript ∪ Python),
+ * refused as {@link PtcBindingNamespace.global} / error-class names by all
+ * backends, one per language: the released TypeScript Node process and the
+ * experimental, private CPython subprocess. The portable-identifier contract
+ * promises a namespace list valid on one backend is valid on every backend; a
+ * per-language check would let `lambda` pass the TypeScript backend and fail
+ * the Python one. Extending the seam with a new language means widening this
+ * union (a breaking review of existing binding names, by design).
+ */
+export declare const PORTABLE_RESERVED_WORDS: ReadonlySet<string>;
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        ptcRuntime: PtcRuntime;
+    }
+}
+/**
+ * Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
+ * failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
+ * structured-cloneable bindings, materialize each declared namespace rejection
+ * class, treat programs as hostile peers, isolate runs from one another, and
+ * terminate and await in-flight runs during disposal.
+ */
+export declare abstract class PtcRuntime extends Service {
+    /**
+     * The source language {@link run} expects `program` to be written in, as a
+     * lowercase identifier. Informational, not gating — a consumer that
+     * generates language-specific presentation (typed SDK stubs, usage
+     * instructions) switches on it and fails loud on a language it cannot
+     * present. Well-known values: `'typescript'` and `'python'`, those
+     * `qilin-tools` presents; the TypeScript backend is released, the Python
+     * backend is experimental and private (not published).
+     */
+    abstract readonly language: string;
+    /**
+     * The execution substrate, as a lowercase identifier. Informational, not
+     * gating — a descriptor so deployments and diagnostics can tell backends
+     * apart, not a security claim. Well-known values: `'worker-thread'`,
+     * `'process'`, `'container'`.
+     */
+    abstract readonly isolation: string;
+    /** Provider-owned program usage guidance for consumers to present alongside the source language. */
+    get executionInstructions(): string;
+    /** Deployment file-policy mode, or undefined for a provider without confinement support. */
+    get sandboxMode(): SandboxMode | undefined;
+    /** Configured numeric elapsed-time defaults and cap, or undefined when per-call overrides are unsupported. */
+    get timeout(): {
+        defaultMs: number;
+        maxMs: number;
+    } | undefined;
+    constructor(ctx: Context);
+    /**
+     * Resolve supported options and provider defaults before execution.
+     * @param request - Program, bindings, cancellation and optional execution choices.
+     * @returns Complete directory, deadline and supported authority for run.
+     * @throws When an explicit choice is invalid or unsupported by this provider.
+     */
+    abstract resolve(request: PtcRunRequest): PtcRunSpec;
+    /**
+     * Execute resolved inputs; program outcomes resolve as result fields.
+     * @param spec - directory, deadline, program, bindings, cancellation and supported policy.
+     * @returns Captured output and the execution outcome.
+     */
+    abstract run(spec: PtcRunSpec): Promise<PtcRunResult>;
+}
+export default PtcRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Vocabulary types for the PTC execution seam: what a caller hands a
+ * {@link ../index.ts | PtcRuntime} and what it gets back. Pure types — no
+ * runtime code lives here.
+ *
+ * @module @qilin-agent/ptc-runtime/src/types
+ */
+import type { SandboxEnforcement, SandboxExecutionPolicy, SandboxMode } from '@qilin-agent/sandbox';
+/**
+ * One host-side function exposed to the program as an async callable. The
+ * runtime bridges calls to it (possibly across a serialization boundary), so
+ * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
+ * lossy or non-cloneable value with a descriptive error rather than corrupting
+ * the run. No seam-level byte cap applies to a binding resolution. A rejection
+ * of this function surfaces inside the program as a rejection of the
+ * corresponding call.
+ */
+export type PtcBindingFunction = (args: unknown) => Promise<PtcJsonValue>;
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
+export type PtcJsonValue = null | boolean | number | string | PtcJsonValue[] | {
+    [key: string]: PtcJsonValue;
+};
+/**
+ * Program-visible typed rejection for one binding namespace. The runtime
+ * injects a real error constructor under `name`; rejected member calls become
+ * its instances and expose the exact member name through
+ * `memberNameProperty`. Both strings are runtime data rather than knowledge
+ * of a particular consumer such as PTC mode.
+ */
+export interface PtcBindingErrorClass {
+    /** Constructor global and resulting `Error.name`; same portable identifier rule as {@link PtcBindingNamespace.global}. */
+    name: string;
+    /**
+     * Non-empty own property for the member name. The portable exclusion set is
+     * `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
+     * middle), enforced identically by every backend; any other name —
+     * identifiers or not — is accepted everywhere.
+     */
+    memberNameProperty: string;
+}
+/**
+ * A named group of {@link PtcBindingFunction}s the runtime exposes to the
+ * program as one global object (e.g. `tools`). Function names are arbitrary
+ * strings — a runtime must treat names like `__proto__` or `constructor` as
+ * ordinary own properties (null-prototype construction), never as prototype
+ * collisions.
+ */
+export interface PtcBindingNamespace {
+    /**
+     * The global identifier the program sees. Must match the LANGUAGE-PORTABLE
+     * identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
+     * words, so the same namespace list works against every backend regardless
+     * of `language` — a JS-only spelling like `$tools` is rejected by design,
+     * not just by the Python backend. Names that satisfy the identifier rule but
+     * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
+     * `__qilin_main__`) are also refused everywhere; see its declaration for the
+     * exact set and why each entry is reserved.
+     */
+    global: string;
+    /** The callable members, keyed by the exact name the program calls. */
+    functions: Record<string, PtcBindingFunction>;
+    /** Optional program-visible typed rejection contract for this namespace. */
+    errorClass?: PtcBindingErrorClass;
+}
+/**
+ * Caller inputs for one program. The provider's resolve method validates supported
+ * options and supplies directory, deadline, and authority before execution.
+ */
+export interface PtcRunRequest {
+    /**
+     * The program source, in the runtime's {@link ../index.ts | language}. It
+     * runs as the body of an async function: top-level `await` and `return`
+     * are available, and the completion value becomes
+     * {@link PtcRunResult.value}.
+     */
+    program: string;
+    /** Host functions exposed to the program, one global object per namespace. */
+    bindings: PtcBindingNamespace[];
+    /** Working directory in the mounted filesystem and subprocess execution world. */
+    cwd?: string;
+    /**
+     * Elapsed execution budget in milliseconds. Omission uses provider defaults;
+     * null requests no deadline. Providers validate and cap numeric budgets or reject unsupported choices.
+     */
+    timeoutMs?: number | null;
+    /** Resolved authority for this execution. Providers without confinement reject an explicit policy. */
+    sandboxPolicy?: SandboxExecutionPolicy;
+    /**
+     * Abort the run: the runtime stops the program (hard, even mid-loop) and
+     * resolves with a {@link PtcRunFailure} of kind `'abort'`. In-flight
+     * binding calls are the CALLER's to settle — the runtime only stops asking.
+     */
+    signal?: AbortSignal;
+}
+/** Fully resolved execution inputs; run never supplies a missing directory or deadline choice. */
+export interface PtcRunSpec extends PtcRunRequest {
+    /** Absolute directory in the provider's execution world. */
+    cwd: string;
+    /** Positive finite elapsed budget in milliseconds after provider capping, or null for no deadline. */
+    timeoutMs: number | null;
+}
+/** File confinement applied to a program, independently of its terminal outcome. */
+export interface PtcRunSandbox {
+    /** File-effect mode used for this execution. */
+    mode: SandboxMode;
+    /** Program failure text matched backend diagnostics; not enforcement proof or an exhaustive denial record. */
+    denied: boolean;
+    /** Completeness reported by the selected confining backend; absent for full access. */
+    enforcement?: SandboxEnforcement;
+}
+/**
+ * Why a run failed. The kinds are orthogonal outcomes reported independently
+ * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * abort is not a timeout, and a substrate death is neither.
+ *
+ * - `'exception'` — the program threw or failed to parse/transform.
+ * - `'timeout'` — an implementation-owned budget expired; the message says which.
+ * - `'abort'` — {@link PtcRunRequest.signal} fired.
+ * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ * - `'invalid-output'` — the completion value was not lossless JSON.
+ * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
+ * - `'protocol'` — the program sent invalid or over-budget control traffic.
+ * - `'sandbox-unavailable'` — required confinement could not be established.
+ */
+export interface PtcRunFailure {
+    /** The failure class (see the interface doc for each kind's meaning). */
+    kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit' | 'protocol' | 'sandbox-unavailable';
+    /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+    message: string;
+}
+/**
+ * The outcome of one run. An error is a FIELD on a resolved result, never a
+ * rejection of `run()` — reporting a failed program is the caller's job, not
+ * an exception path.
+ */
+export interface PtcRunResult {
+    /** Applied file policy and observed denial, when the provider enforces file policy. */
+    sandbox?: PtcRunSandbox;
+    /**
+     * The program's completion value (its top-level `return`), when it ran to
+     * completion and the value crossed the runtime's lossless-JSON boundary.
+     * Invalid or over-limit completions fail the run instead of substituting a
+     * rendered string; a failed or value-less run leaves this absent.
+     */
+    value?: PtcJsonValue;
+    /**
+     * Captured text. Each source channel preserves emission order; interleaving
+     * across independent channels is backend-dependent. Bounded only as part of
+     * the outer result.
+     */
+    logs: string[];
+    /** Present iff the run failed; see {@link PtcRunFailure} for the taxonomy. */
+    error?: PtcRunFailure;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@qilin-agent/ptc-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract PTC execution seam (ctx.ptcRuntime) for the QiLin",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/ptc-runtime/ptc-runtime"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/sandbox": "3.1.3"
+  }
 }