@rong/agentscript 0.1.3 → 0.1.5

package/docs/en/context-engineering.md

@@ -1,322 +1,104 @@
 # 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({
-    goal: input.goal
+    goal: input.goal,
     previous: results.summary
 })
 ```
 
-`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

@@ -175,11 +175,11 @@ For typical LLM calls, omit `return`:
 
 ```agentscript
 func summarize(content) {
-    use content < 8k
+    use content max 8k
 
     generate({
-        input: "Summarize the content"
-        limit: 1000
+        input: "Summarize the content",
+        max_output: 1000
     }) -> {
         title string
         summary string