@rong/agentscript 0.1.3 → 0.1.4

package/docs/cn/use-as.md

@@ -0,0 +1,225 @@
+# `use ... as ...`
+
+本文档定义 AgentScript 中 `use` 如何选择 prompt context，包括 context label、budget、scope 可见性、延迟求值和 trace 要求。
+
+整体模型见 [Context Engineering](./context-engineering.md)。Prompt 构造和输出契约见 [`generate`](./generate.md)。
+
+## 目的
+
+`use` 不是变量读取、赋值或命名空间导入。它声明一个 prompt context source。
+
+```agentscript
+use input.question as user question
+use scratch.summary < 2k as observations
+```
+
+含义是：
+
+```text
+让这个 source 对当前作用域及子作用域中后续的 generate 可见
+```
+
+没有被 `use` 选择的局部变量不会进入 prompt。
+
+## 语法
+
+```agentscript
+use expr
+use expr < budget
+use expr as label
+use expr < budget as label
+```
+
+固定顺序是：
+
+```text
+选择什么 -> 限制多少 -> 作为何种上下文
+```
+
+示例：
+
+```agentscript
+use input.question as user question
+use docs.summary < 4k as retrieved evidence
+use scratch.summary < 2k as observations
+```
+
+## Context label
+
+`as` 后面的 label 是字面标签文本，不是表达式，不会求值，也不会读取作用域中的变量。
+
+```agentscript
+use docs as evidence
+use docs.summary < 4k as retrieved evidence
+use input.question as user
+```
+
+即使当前作用域中存在名为 `evidence` 的变量，`as evidence` 也只是把 context section 标记为 `evidence`。
+
+Label 影响：
+
+- prompt section label
+- trace display
+- context organization
+- debug 和 audit 可读性
+
+Label 不影响：
+
+- agent identity
+- provider message role
+- tool 权限
+- system/user/assistant 权限
+
+## Provider role 不是 context label
+
+`system`、`user`、`assistant`、`tool` 等 provider role 是 LLM API 的传输协议细节。AgentScript context label 是 prompt 内部组织标签。
+
+为避免和 provider role 混淆，以下 label 保留：
+
+```text
+system
+assistant
+tool
+developer
+```
+
+`user` 允许作为 context label，因为它常用于表达“这段 context 是用户输入”。它仍然不会创建单独的 provider `user` message。
+
+## 延迟求值
+
+`use expr` 声明的是 source，不是快照。表达式会在可见的 `generate` 构建 prompt 时求值。
+
+```agentscript
+main func(input) {
+    scratch = []
+    use scratch.summary < 2k as observations
+
+    scratch.add({ fact: "A" })
+    scratch.add({ fact: "B" })
+
+    generate({ input: "Answer from observations" }) -> {
+        text string
+    }
+}
+```
+
+该 `generate` 能看到两个 fact。
+
+这让 `use` 保持为 context contract，而不是一次值复制。
+
+## Scope 可见性
+
+`use` 声明对同一作用域和子作用域中后续的 `generate` 可见。
+
+```agentscript
+use input.question as user question
+
+if input.needs_detail {
+    use input.detail as detail
+    generate({ input: "Answer with detail" }) -> {
+        text string
+    }
+}
+```
+
+内部 `generate` 可以看到 `user question` 和 `detail`。`detail` context 不会泄漏到 block 外部。
+
+Function 和 Agent 调用形成独立 context boundary。Callee 不会自动继承 caller 选择的 context。
+
+## 不能 use 什么
+
+Runtime capability 不能进入 prompt context：
+
+- imported tool
+- imported LLM/model binding
+- imported agent binding
+- memory handle
+- function binding
+- provider URI 和 workspace/runtime 配置
+
+非法示例：
+
+```agentscript
+use Search
+use Qwen
+use Worker
+use helper
+```
+
+应改为使用这些 capability 返回的数据：
+
+```agentscript
+results = Search.search(input.question)
+use results < 4k as search results
+```
+
+## Budget 语义
+
+`use expr < budget` 是 context item budget，限制该 source 渲染进 prompt 的大小。
+
+```agentscript
+use docs.summary < 4k as evidence
+```
+
+这不同于 `generate({ max_output: ... })` 的 output generation budget。详见 [`generate`](./generate.md)。
+
+## Prompt 渲染
+
+带 label 的 context item 渲染为 context section：
+
+```text
+Context:
+[user question]
+source: input.question
+What is AgentScript?
+
+[observations]
+source: scratch.summary
+[
+  { "fact": "..." }
+]
+```
+
+如果没有 label，renderer 可以使用数字 context index，并单独显示 source expression。
+
+## Trace 要求
+
+`use` trace event 记录声明信息：
+
+```json
+{
+  "kind": "use",
+  "data": {
+    "source": "scratch.summary",
+    "label": "observations",
+    "budget": { "amount": 2, "unit": "k" }
+  }
+}
+```
+
+`generate` 的 built context item 记录解析后的值和渲染元数据：
+
+```json
+{
+  "index": 0,
+  "source": "scratch.summary",
+  "label": "observations",
+  "value": [{ "fact": "A" }],
+  "text": "[...]",
+  "budget": { "amount": 2, "unit": "k" },
+  "clipped": false
+}
+```
+
+Trace 必须让 source、label、budget、clipping 状态和 resolved value 可审计。
+
+## 设计检查清单
+
+修改 `use` 前，应检查：
+
+- 未使用的数据是否仍然不会进入 prompt？
+- source 是否仍在 `generate` 时求值？
+- label 是否仍是字面文本，而不是表达式？
+- provider role 是否仍与 context label 分离？
+- budget 是否仍附着在 context item 上，而不是整个 generation 上？
+- function 和 Agent boundary 是否仍能阻止 context 泄漏？

package/docs/en/context-engineering.md

@@ -1,120 +1,69 @@
 # AgentScript Context Engineering
 
-This document explains the core design semantics of `use`, scopes, and `generate` in AgentScript. These concepts are not specific to any version — they are the fundamental semantics that distinguish AgentScript from general-purpose programming languages.
+This document is the top-level design map for AgentScript context engineering. It explains why AgentScript exists, what boundaries it enforces, and how the detailed `use ... as ...` and `generate` documents fit together.
 
-AgentScript has variables, functions, loops, and agent calls, but its primary purpose is not to be a general-purpose language. It is an auditable, composable, explicit prompt context engineering DSL.
+AgentScript has variables, functions, loops, tools, memory, and agent calls, but its purpose is not to be a general-purpose programming language. Its purpose is to make prompt context explicit, scoped, typed, traceable, and auditable.
 
-## Core positioning
+## Document structure
 
-AgentScript's control flow serves prompt context construction.
+The context engineering design is split into three documents:
 
-Ordinary statements organize data, call tools, call agents, and update intermediate state. LLM calls happen only through `generate(...) -> { ... }`, and the context visible to `generate` must be declared explicitly with `use`.
+- **Context Engineering**: this overview; explains the mental model and invariants.
+- **[`use ... as ...`](./use-as.md)**: explains how data is selected as prompt context, how labels work, how budgets are applied, and how scope affects visibility.
+- **[`generate`](./generate.md)**: explains generation sites, prompt construction, agent identity, output contracts, budgets, retries, and trace output.
 
-The core objects are:
-
-- **Data**: ordinary variables, JSON values, lists, file imports, tool observations, agent return values.
-- **Context Source**: a prompt context origin declared by `use expr < budget`.
-- **Generation Site**: an LLM call declared by `generate({ input, limit, attempts, debug }) -> shape`.
-- **Boundary**: context visibility boundaries formed by agent, function, and block scopes.
-
-## Semantics of `use`
-
-`use` is not a variable read or a namespace import. Its meaning is:
-
-> Declare a prompt context source in the current scope, so that `generate` calls visible in that scope may include the source's current value in the prompt context.
-
-Example:
-
-```agentscript
-func answer(question, scratch) {
-    use question
-    use scratch.summary < 2k
-
-    generate({
-        input: "Answer the question using collected facts"
-        limit: 800
-    }) -> {
-        ok boolean
-        text string
-        error string
-    }
-}
-```
+The language reference remains the compact syntax reference. These design documents define the intended semantics.
 
-Here `question` and `scratch.summary` are explicit context sources for the `generate` call. Local variables not selected by `use` must not enter the prompt.
+## Core model
 
-### Deferred evaluation
+AgentScript control flow serves prompt context construction.
 
-`use expr < budget` declares a context source, not a snapshot of the current value. The source is resolved at the `generate` execution point.
+Ordinary statements organize data, call tools, call agents, query memory, and update intermediate state. LLM calls happen only through `generate(...) -> { ... }`. A `generate` call sees only context sources explicitly declared with `use` and visible through scope.
 
-```agentscript
-main func(input) {
-    scratch = []
-    use scratch.summary < 2k
-
-    scratch.add({ fact: "A" })
-    scratch.add({ fact: "B" })
-
-    generate({ input: "Answer from scratch" }) -> {
-        text string
-    }
-}
-```
-
-The `generate` call sees both facts.
-
-Rationale:
-
-- `use` expresses a context contract, not an assignment.
-- Agent patterns continuously update scratch, plans, and observations.
-- A snapshot-based `use` would require re-declaration before every `generate`, risking stale context.
+The core objects are:
 
-### What cannot be used
+- **Data**: ordinary values such as input, JSON, lists, file contents, tool observations, memory query results, and agent return values.
+- **Context source**: data selected for prompt context by `use expr`, optionally with a budget and label.
+- **Generation site**: one LLM call expressed by `generate({ input, max_output, attempts, temperature, think, strict, debug }) -> shape`.
+- **Boundary**: a visibility boundary formed by an agent, function, or block scope.
+- **Trace**: the audit record explaining which sources were selected, how prompt context was built, and what each generation returned.
 
-The following runtime capabilities must never enter prompt context:
+## Key invariants
 
-- Imported tools
-- Imported LLMs / models
-- Imported agent bindings
-- Function bindings
-- Provider URIs, workspace paths, and other execution configuration
+AgentScript should preserve these invariants:
 
-These should be rejected by the semantic analyzer:
+- **No implicit capture**: local variables, tool outputs, memory records, and trace events do not enter prompts unless selected with `use`.
+- **Scoped visibility**: context visibility follows scope. Child scopes can inherit parent context; function and agent calls create independent context boundaries.
+- **Capability isolation**: imported tools, models, agents, memory handles, functions, provider URIs, and runtime configuration are capabilities, not prompt data.
+- **Deferred context resolution**: `use expr` declares a source. The value is resolved when a visible `generate` builds its prompt.
+- **Layered prompts**: prompts distinguish agent identity, selected context, instruction, and output contract.
+- **Auditable traces**: trace output must explain what the LLM call actually saw, including source expressions, labels, budgets, clipping, and generated results.
 
-```agentscript
-use Search     -- invalid (tool binding)
-use Qwen       -- invalid (LLM binding)
-use Worker     -- invalid (agent binding)
-use helper     -- invalid (function binding)
-```
-
-## Scope as context boundary
-
-Scopes in AgentScript control both variable visibility and prompt context visibility.
+## Boundary model
 
 ### Function boundary
 
-Each function call creates an independent context boundary.
+Each function call has its own context boundary. A callee does not automatically inherit the caller's selected context. Data must be passed as an argument and selected again when the callee wants it in its own prompt.
 
 ```agentscript
 func caller(input) {
-    use input.goal
+    use input.goal as goal
     helper(input)
 }
 
 func helper(input) {
-    use input.detail
+    use input.detail as detail
     generate({ input: "Work on detail" }) -> {
         ok boolean
     }
 }
 ```
 
-The `generate` inside `helper` must not inherit `caller`'s `use input.goal`. Data must be passed as arguments and explicitly `use`d.
+The `generate` inside `helper` sees `input.detail`, not `caller`'s `input.goal`.
 
 ### Agent boundary
 
-Agent calls create a stronger context boundary.
+Agent calls create a stronger boundary. A called agent does not see the caller's prompt context. It sees only its input value and the context selected by its own functions.
 
 ```agentscript
 result = Worker({
@@ -123,200 +72,33 @@ result = Worker({
 })
 ```
 
-`Worker` must not see the caller's context. The caller passes data explicitly through arguments.
-
-This guarantees:
-
-- Each agent's prompt contract is independently auditable.
-- Multi-agent composition does not cause implicit context leakage.
-- Sub-agents see only explicitly passed data.
+This keeps multi-agent composition auditable: each agent has its own prompt contract.
 
 ### Block boundary
 
-Blocks (`if`, `repeat`, `loop`, `for`) create child scopes. `use` declarations inside a block affect only `generate` calls within that block.
-
-```agentscript
-if condition {
-    temp = compute(input)
-    use temp
-    result = generate({ input: "Use temp" }) -> {
-        ok boolean
-    }
-}
-```
-
-`temp` and `use temp` must not leak to the outer scope.
-
-### Parent context visibility
+Blocks such as `if`, `repeat`, `loop`, and `for` create child scopes. Context declared inside the block affects `generate` calls inside that block and does not leak upward.
 
-A `generate` call in a nested scope can see context sources declared in parent scopes. The visible order must be stable from outer to inner for trace and prompt audit.
+## Prompt layers
 
-## Context construction model
+A `generate` call is built from four conceptual layers:
 
-A `generate` call's prompt consists of four layers.
+1. **Agent identity**: current agent `role`, `description`, and stable behavioral identity.
+2. **Selected context**: visible `use` declarations, rendered with source, label, value, and budget information.
+3. **Instruction**: the per-call task from `generate({ input: ... })`.
+4. **Output contract**: the optional `-> { ... }` shape.
 
-### System
-
-Describes agent identity and stable behavioral constraints:
-
-- Agent name
-- `role`
-- `description`
-
-Must not contain execution configuration (provider URIs, workspace paths, tool internals).
-
-### Context
-
-Comes from `use` declarations visible to the current `generate`.
-
-Each context item records:
-
-- source expression (e.g. `scratch.summary`)
-- resolved value
-- rendered text
-- budget
-- clipping status
-
-Recommended prompt format:
-
-```text
-Context:
-[0] question:
-What is AgentScript?
-
-[1] scratch.summary:
-[
-  { "fact": "..." }
-]
-```
-
-Source labels help models understand context and help humans audit prompts.
-
-### Instruction
-
-Comes from the `input` field of `generate(...)` options.
-
-```agentscript
-generate({ input: "Answer the question using only collected facts" }) -> {
-    ok boolean
-    text string
-}
-```
-
-The instruction is the per-call task. `limit`, `attempts`, and `debug` are local configuration, not prompt context. Error feedback from previous failed attempts is appended to the instruction.
-
-### Output contract
-
-Comes from the optional `-> { ... }` shape on a `generate` expression.
-
-```agentscript
-generate({ input: "Answer" }) -> {
-    ok boolean
-    text string
-    error string
-}
-```
-
-The LLM provider and runtime enforce shape compliance as strictly as possible.
-
-## Budget semantics
-
-`use expr < budget` is a **context item budget**. It limits how much of that source may be rendered into the prompt.
-
-`generate({ limit: budget })` is a **generation budget**. It limits output size or the provider's token limit.
-
-They have different meanings and must not be confused.
-
-Character count is used as an approximation. Future implementations may switch to token-aware budgets without changing the abstraction.
-
-## Clipping strategy
-
-Context clipping must not simply truncate strings, as that would break JSON and list structure.
-
-Strategy:
-
-- Strings: may be truncated by character count.
-- Lists: prefer keeping complete items, dropping from the tail.
-- Objects: prefer keeping complete fields, dropping from the tail.
-- Trace: record original size, clipped size, and strategy for each item.
-
-## Trace requirements
-
-Trace is the primary debugging interface for a context engineering DSL.
-
-`use` trace:
-
-```json
-{
-  "kind": "use",
-  "data": {
-    "source": "scratch.summary",
-    "budget": { "amount": 2, "unit": "k" }
-  }
-}
-```
-
-`generate` trace:
-
-```json
-{
-  "kind": "generate",
-  "data": {
-    "instruction": "Answer from scratch",
-    "context": {
-      "items": [
-        {
-          "source": "scratch.summary",
-          "value": [{ "fact": "A" }],
-          "text": "[...]",
-          "budget": { "amount": 2, "unit": "k" },
-          "clipped": false
-        }
-      ]
-    }
-  }
-}
-```
-
-This answers:
-
-- What did the LLM call actually see?
-- Which context sources were declared but not included?
-- What was clipped?
-- Which expression was the source resolved from?
-- Did caller and callee contexts leak?
-
-## The `summary` view
-
-`scratch.summary` is a common pattern:
-
-```agentscript
-scratch = []
-scratch.add(observation)
-use scratch.summary < 2k
-```
-
-It expresses "put the prompt-friendly view of scratch into context." If the implementation provides only a JSON-safe list view rather than a true LLM summary, this should be documented and visible in the trace.
-
-## Implementation constraints
-
-Future changes must respect:
-
-- `generate` does not automatically capture local variables.
-- `use` is a context declaration, not an assignment.
-- `use` values are resolved when `generate` builds the prompt.
-- Function and agent calls form context boundaries.
-- Runtime capabilities must never enter prompt context.
-- Prompts must distinguish system, context, instruction, and output contract layers.
-- Trace must explain every `generate` call's actual context.
+See [`generate`](./generate.md) for the detailed construction rules.
 
 ## Design checklist
 
-Before modifying `use`, scope, context builder, trace, or the LLM provider, verify:
+Before changing `use`, scope, context builder, trace, or LLM provider behavior, verify:
+
+- Does this let unused data enter a prompt?
+- Does this let caller context pollute a callee?
+- Does this expose tool/model/agent/function bindings as prompt data?
+- Does this preserve source, label, budget, and clipping information for audit?
+- Does this reduce `use` to a snapshot assignment instead of a deferred context source?
+- Does this confuse context budget with generation budget?
+- Does this confuse AgentScript context labels with provider message roles?
 
-- Does this change let unused data enter the prompt?
-- Does this change let caller context implicitly pollute callee?
-- Does this change expose tool/model/agent/function bindings as prompt data?
-- Does this change preserve audit information for context sources?
-- Does this change reduce `use` to an ordinary variable snapshot?
-- Does this change confuse context budget with generation budget?
+AgentScript's core value is not another control-flow syntax. Its value is making prompt context source, scope, budget, identity, and final prompt shape explicit and stable.

package/docs/en/final-expression-return.md

@@ -179,7 +179,7 @@ func summarize(content) {
 
     generate({
         input: "Summarize the content"
-        limit: 1000
+        max_output: 1000
     }) -> {
         title string
         summary string