@rong/agentscript 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to AgentScript will be documented in this file.
 
+## 0.1.3 - 2026-05-08
+
+### Added
+
+- Added final expression return for functions.
+- Added literal context labels with `use context as label`.
+- Added agent role and description to prompt identity construction.
+- Added trace and built context output for context labels.
+
+### Changed
+
+- Updated README, examples, and language references for labeled context usage.
+
 ## 1.0.0 - 2026-05-07
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # AgentScript
 
 > **Agent context as code.**
-> `use` declares what the model can see.
+> `use` declares what the model can see, with optional labels for prompt sections.
 > `generate` defines the only LLM call site and optional output shape.
 > Zero runtime dependencies. TypeScript-powered.
 
 ```agentscript
-use scratch.summary < 2k
+use scratch.summary < 2k as observations
 generate({ input: "Answer from observations" }) -> {
     ok boolean
     text string
@@ -61,8 +61,8 @@ main agent FileSummarizer {
 
     main func(input { path string }) {
         content = File.read({ path: input.path })
-        use input.path
-        use content < 8k
+        use input.path as source path
+        use content < 8k as file content
 
         generate({
             input: "Summarize the file for a busy teammate"
@@ -113,7 +113,7 @@ It is a small language for one thing:
 
 > making LLM prompt context explicit, scoped, typed, traceable, and compilable.
 
-It gives you two things that general-purpose languages don't: a first-class `use` keyword that declares *which* data enters the LLM prompt, and a first-class `generate` expression that defines an LLM call with an optional output contract. Everything else — variables, functions, agents, imports, loops — exists to support this core workflow. Scopes enforce context boundaries naturally: what's `use`d in one function stays there; child scopes inherit but never leak upward. Functions can also return their final top-level expression directly, which keeps typical LLM workflows concise.
+It gives you two things that general-purpose languages don't: a first-class `use` keyword that declares *which* data enters the LLM prompt and what role it plays via `as label`, and a first-class `generate` expression that defines an LLM call with an optional output contract. Everything else — variables, functions, agents, imports, loops — exists to support this core workflow. Scopes enforce context boundaries naturally: what's `use`d in one function stays there; child scopes inherit but never leak upward. Functions can also return their final top-level expression directly, which keeps typical LLM workflows concise.
 
 ## How it works
 
@@ -178,10 +178,10 @@ main agent ResearchAgent {
     main func(input {
         question string
     }) {
-        use input.question
+        use input.question as user question
 
         scratch = []
-        use scratch.summary < 2k
+        use scratch.summary < 2k as observations
 
         done = false
         loop until done < 6 {
@@ -195,8 +195,8 @@ main agent ResearchAgent {
     }
 
     func answer(question, scratch) {
-        use question
-        use scratch.summary < 2k
+        use question as user question
+        use scratch.summary < 2k as observations
         generate({ input: "Answer using only the observations" }) -> {
             ok boolean
             text string
@@ -208,7 +208,7 @@ main agent ResearchAgent {
 
 ## Key ideas
 
-1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d
+1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d; `as label` names the context section
 2. **`generate` is the only LLM call site** — with a required input instruction and optional output shape
 3. **Final expression return keeps flows concise** — a function returns its final top-level expression
 4. **Scope is context boundary** — functions, agents, and blocks isolate prompt visibility
@@ -219,7 +219,7 @@ main agent ResearchAgent {
 
 | | Python / TypeScript | AgentScript |
 |---|---|---|
-| Context management | Implicit (string concatenation, array append) | Explicit (`use` declaration) |
+| Context management | Implicit (string concatenation, array append) | Explicit (`use` declaration, optional `as label`) |
 | LLM call site | Anywhere in the code | One `generate` expression |
 | Context isolation | Manual discipline | Scope-inherited, auto-isolated |
 | Trace / audit | External tooling needed | Built-in, per-call |

package/dist/parser/parser.js

@@ -176,13 +176,26 @@ class Parser {
         const start = this.consume("use").range.start;
         const value = this.parseLogicalOr();
         const budget = this.match("<") ? this.parseBudget() : undefined;
+        const label = this.match("as") ? this.parseUseLabel() : undefined;
         return {
             kind: "UseStmt",
             value,
             budget,
+            label,
             range: { start, end: this.previous().range.end }
         };
     }
+    parseUseLabel() {
+        const tokens = [];
+        const line = this.previous().range.start.line;
+        while (!this.isAtEnd() && !this.check("}") && this.peek().range.start.line === line) {
+            tokens.push(this.advance());
+        }
+        if (tokens.length === 0) {
+            throw this.error("Expected context label after 'as'");
+        }
+        return stringifyLabelTokens(tokens);
+    }
     parseConfigValue(key) {
         if (key === "model") {
             return this.parsePostfix();
@@ -656,3 +669,15 @@ class Parser {
 function isImportResourceKind(value) {
     return IMPORT_RESOURCE_KINDS.has(value);
 }
+function stringifyLabelTokens(tokens) {
+    let label = tokens[0]?.value ?? "";
+    for (let index = 1; index < tokens.length; index += 1) {
+        const previous = tokens[index - 1];
+        const current = tokens[index];
+        if (current.range.start.column > previous.range.end.column) {
+            label += " ";
+        }
+        label += current.value;
+    }
+    return label;
+}

package/dist/runtime/context.js

@@ -51,6 +51,7 @@ function buildContextItem(item, index) {
     return {
         index,
         source: item.source,
+        label: item.label,
         value: clipped.value,
         text: clipped.text,
         budget: item.budget,
@@ -60,8 +61,15 @@ function buildContextItem(item, index) {
     };
 }
 function buildSystemPrompt(agentName, identity) {
-    const lines = [`You are ${agentName}.`];
+    const role = typeof identity.role === "string" ? identity.role : agentName;
+    const lines = [`You are ${role}.`];
+    if (typeof identity.description === "string") {
+        lines.push(identity.description);
+    }
     for (const [key, value] of Object.entries(identity)) {
+        if (key === "role" || key === "description") {
+            continue;
+        }
         lines.push(`${key}: ${renderJson(value)}`);
     }
     return lines.join("\n");
@@ -71,8 +79,9 @@ function buildFinalUserMessage(context, instructionText, returnSchema) {
     if (context.length > 0) {
         sections.push("Context:");
         for (const item of context) {
-            const label = item.source ? `${item.source}:\n` : "";
-            sections.push(`[${item.index}] ${label}${item.text}`);
+            const label = item.label ?? String(item.index);
+            const source = item.source ? `source: ${item.source}\n` : "";
+            sections.push(`[${label}]\n${source}${item.text}`);
         }
     }
     sections.push("Instruction:", instructionText);
@@ -147,6 +156,7 @@ export function builtContextToJson(context) {
         context: context.context.map((item) => ({
             index: item.index,
             source: item.source ?? null,
+            label: item.label ?? null,
             value: item.value,
             text: item.text,
             budget: budgetToJson(item.budget),

package/dist/runtime/evaluator.js

@@ -80,6 +80,7 @@ export class Evaluator {
         for (const item of scope.visibleUses()) {
             uses.push({
                 source: item.source,
+                label: item.label,
                 value: await this.evaluate(item.expr, item.scope),
                 budget: item.budget,
             });

package/dist/runtime/interpreter.js

@@ -209,8 +209,11 @@ class Interpreter {
                 return undefined;
             case "UseStmt": {
                 const source = formatExpressionSource(stmt.value);
-                scope.addUse(stmt.value, source, stmt.budget);
-                this.trace.push({ kind: "use", data: { source, budget: budgetToJson(stmt.budget) } });
+                scope.addUse(stmt.value, source, stmt.budget, stmt.label);
+                this.trace.push({
+                    kind: "use",
+                    data: { source, label: stmt.label ?? null, budget: budgetToJson(stmt.budget) },
+                });
                 return undefined;
             }
             case "AssignStmt": {

package/dist/runtime/scope.js

@@ -29,8 +29,8 @@ export class RuntimeScope {
         }
         this.define(name, value);
     }
-    addUse(expr, source, budget) {
-        this.uses.push({ expr, source, budget, scope: this });
+    addUse(expr, source, budget, label) {
+        this.uses.push({ expr, source, budget, label, scope: this });
     }
     setConfig(name, value) {
         this.config.set(name, value);

package/dist/semantic/analyzer.js

@@ -171,6 +171,9 @@ class Analyzer {
                 if (stmt.budget && stmt.budget.amount <= 0) {
                     this.error("INVALID_BUDGET", "Budget amount must be greater than 0", stmt.range);
                 }
+                if (stmt.label && RESERVED_CONTEXT_LABELS.has(stmt.label)) {
+                    this.error("RESERVED_CONTEXT_LABEL", `Context label '${stmt.label}' is reserved`, stmt.range);
+                }
                 break;
             case "AssignStmt":
                 this.checkAssignment(stmt, scope);
@@ -501,6 +504,7 @@ class Analyzer {
 const IMPORTED_BINDING_KINDS = new Set(["tool", "llm", "file", "agent", "memory"]);
 const NON_CONTEXT_BINDING_KINDS = new Set(["tool", "llm", "agent", "function", "memory"]);
 const VALID_MEMORY_METHODS = new Set(["add", "query"]);
+const RESERVED_CONTEXT_LABELS = new Set(["system", "assistant", "tool", "developer"]);
 function functionBinding(agentName, fn) {
     return {
         kind: "function",

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

@@ -59,6 +59,24 @@ func run(input) {
 }
 ```
 
+这条规则适用于所有表达式形式，包括调用表达式。被调用者解析为本地函数还是 agent 调用，都不影响 final expression return。例如，直接用 agent 名称调用另一个 agent 时，会调用该 agent 的 `main func`，其结果会被隐式返回：
+
+```agentscript
+agent Planner {
+    main func(input) {
+        generate({ input: "Create a plan" }) -> {
+            steps list[string]
+        }
+    }
+}
+
+agent Controller {
+    func run(input) {
+        Planner(input)
+    }
+}
+```
+
 ```agentscript
 func get_result(result) {
     result.value

package/docs/cn/language.md

@@ -158,6 +158,8 @@ Shape 不是完整的静态类型系统。
 use input.question
 use Requirements < 4k
 use past_lessons < 2k
+use input.question as user
+use docs.summary < 4k as evidence
 ```
 
 ### 规则
@@ -167,10 +169,24 @@ use past_lessons < 2k
 - Memory 查询结果不会自动进入 prompt。
 - Trace 事件不会自动进入 prompt。
 - `use value < n` 应用上下文预算。
+- `use value as label` 为选中的 context source 附加字面标签。
+- `use value < n as label` 先应用预算，再附加标签。
 - `llm`、`tool`、`agent`、`memory` 绑定不能被 `use`。
 - 函数绑定不能被 `use`。
 - `use` 声明被子作用域继承。
 
+### 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 和 trace 输出；它不会改变 `system`、`user`、`assistant` 等 provider message role。
+
 ### 延迟求值
 
 `use expr < budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。

package/docs/cn/role-label.md

@@ -0,0 +1,492 @@
+# AgentScript Role / Label 设计
+
+本文档定义 AgentScript 中 `agent role`、`context label` 和底层 provider message role 的分层设计，用于指导当前 prompt 构造、`use ... as ...` 语法和 trace 展示的实现。
+
+## 1. 核心结论
+
+AgentScript 应明确区分三类概念：
+
+```text
+agent role 表示“谁在生成 / 谁在发言”。
+context label 表示“这段上下文在当前 prompt 中的用途”。
+provider role 表示底层 LLM API message 的 system/user/assistant/tool。
+```
+
+这三者属于不同层级，不能混用。
+
+- `agent role` 是 AgentScript 层的生成身份。
+- `context label` 是 prompt 内部的上下文组织标签。
+- `provider role` 是 OpenAI / Anthropic / Ollama 等 adapter 的传输协议细节。
+
+用户不应通过 `use ... as system` 之类的写法直接操纵底层 provider role。
+
+## 2. Agent Role
+
+`role` 是 agent 的身份声明：
+
+```agentscript
+agent ResearchAgent {
+    model Qwen
+    role "Senior Researcher"
+    description "Answer questions with search and structured reasoning."
+}
+```
+
+它的含义是：
+
+```text
+当前 agent 以什么身份进行 generate。
+```
+
+每次 `generate` 都应把当前 agent 的 `role` 和 `description` 放入 identity 层 prompt。例如：
+
+```text
+You are a Senior Researcher.
+Answer questions with search and structured reasoning.
+```
+
+因此当前实现目标是：
+
+```text
+agent.role -> generation identity
+agent.description -> generation identity
+```
+
+在 multi-agent 场景中，agent 输出被其他 agent 使用时，`role` 也可以作为 speaker provenance 展示：
+
+```text
+[plan]
+Produced by: Planner
+Role: Planner
+Output:
+...
+```
+
+这里的 `Role: Planner` 仍然是 AgentScript 层的 agent role，不是 provider message role。
+
+## 3. Context Label
+
+Context label 是 `use` 注入上下文时的语义标签。
+
+当前语法支持：
+
+```agentscript
+use expr
+use expr < budget
+use expr as label
+use expr < budget as label
+```
+
+固定顺序是：
+
+```text
+选择什么 -> 限制多少 -> 作为何种上下文
+```
+
+例如：
+
+```agentscript
+use input.question as user
+use scratch.summary < 2k as memory
+use docs.summary < 4k as evidence
+use search_result as observation
+use policy as constraint
+```
+
+`context label` 的含义是：
+
+```text
+这段内容在当前 generate prompt 中作为何种材料被呈现。
+```
+
+它只影响：
+
+- prompt section label
+- trace display
+- context organization
+- debug / audit readability
+
+它不改变：
+
+- agent identity
+- provider message role
+- tool 权限
+- system / user / assistant 权限
+
+## 4. Provider Role
+
+Provider role 是底层 LLM API 的 message role，例如：
+
+```text
+system
+user
+assistant
+tool
+```
+
+它属于 provider adapter 的实现细节。
+
+默认映射：
+
+```text
+system = 当前 agent identity + runtime rules
+user   = generate instruction + selected context + output shape
+```
+
+也就是说，AgentScript 的 context label 应作为 prompt 内部结构渲染，而不是映射为多条 provider message role。
+
+Runtime 不把 memory、evidence、observation 等材料伪装成 assistant message：
+
+```text
+assistant: [memory] ...
+assistant: [evidence] ...
+```
+
+原因是 `assistant` 在 chat protocol 中表示模型真实历史输出，而 memory / evidence / observation 是外部材料。
+
+## 5. Prompt 构造模型
+
+一次 `generate` 的 prompt 分为四层。
+
+### 5.1 Agent Identity
+
+来自当前 agent 的配置：
+
+```agentscript
+role "Senior Researcher"
+description "Answer questions with search and structured reasoning."
+```
+
+渲染为 provider `system` message 的一部分：
+
+```text
+You are a Senior Researcher.
+Answer questions with search and structured reasoning.
+```
+
+### 5.2 Generate Instruction
+
+来自 `generate(...)` 的 `input` 字段：
+
+```agentscript
+generate({
+    input: "Answer using only the selected context"
+}) -> {
+    ok boolean
+    answer string
+}
+```
+
+渲染为：
+
+```text
+Instruction:
+Answer using only the selected context.
+```
+
+### 5.3 Selected Context
+
+来自当前 scope 和父 scope 中可见的 `use` 声明：
+
+```agentscript
+use input.question as user
+use scratch.summary < 2k as memory
+use docs.summary < 4k as evidence
+```
+
+渲染为：
+
+```text
+Context:
+
+[user]
+...
+
+[memory]
+...
+
+[evidence]
+...
+```
+
+如果没有 label，可以使用 source expression 作为默认 label 或显示为普通 context item。
+
+### 5.4 Output Shape
+
+来自 `generate(...) -> shape`：
+
+```agentscript
+generate({ input: "Answer" }) -> {
+    ok boolean
+    answer string
+}
+```
+
+渲染为：
+
+```text
+Required output shape:
+{
+  ok: boolean
+  answer: string
+}
+```
+
+当 `generate` 没有 `-> shape` 时，不应注入输出 schema，也不应要求 provider 结构化输出。
+
+## 6. `use ... as label` 规则
+
+### 6.1 Label 类型
+
+`as` 后面的 label 是语法层面的字面标签，不是表达式，不参与变量解析，也不会求值。
+
+```agentscript
+use docs as evidence
+use scratch as memory
+use docs.summary < 4k as retrieved-evidence
+```
+
+其中：
+
+```text
+evidence
+memory
+retrieved-evidence
+```
+
+都是 context label 的字面值。即使当前作用域中存在名为 `evidence` 或 `memory` 的变量，`as evidence` 和 `as memory` 也不会读取这些变量。
+
+Label 不需要双引号。它不是字符串表达式，而是 `use` 语句的一部分：
+
+```agentscript
+use docs as retrieved evidence
+```
+
+上例中的 label 是字面标签 `retrieved evidence`。Parser 应把 `as` 之后到语句结束之间的内容作为 label 文本；如果存在预算，则 label 位于预算之后：
+
+```agentscript
+use docs.summary < 4k as retrieved evidence
+```
+
+Label 文本应在 AST 中保存为普通字符串，例如：
+
+```json
+{
+  "label": "retrieved evidence"
+}
+```
+
+Label 不支持嵌套表达式、函数调用、字段访问或插值：
+
+```agentscript
+use docs as label_name      -- label 是 "label_name"，不是变量 label_name 的值
+use docs as input.label     -- label 是 "input.label"，不是字段访问结果
+use docs as label()         -- label 是 "label()"，不会调用函数
+```
+
+### 6.2 保留 label
+
+为避免和 provider role 混淆，以下 label 保留，不作为普通 context label 使用：
+
+```text
+system
+assistant
+tool
+developer
+```
+
+`user` 允许作为 context label，但它只是 context label，不是 provider role：
+
+```agentscript
+use input.question as user
+```
+
+这里的 `user` 表示“这段上下文是用户输入”，不是把该 context item 变成 provider `user` message。
+
+### 6.3 继承规则
+
+`use` 声明原本可被 child scope 继承。加入 label 后，label 应随 use declaration 一起继承。
+
+```agentscript
+use input.question as user
+
+func answer() {
+    generate({ input: "Answer" }) -> {
+        answer string
+    }
+}
+```
+
+`answer()` 内部的 `generate` 仍可看到：
+
+```text
+[user]
+input.question
+```
+
+### 6.4 重复 label
+
+允许多个 context source 使用同一个 label：
+
+```agentscript
+use docs1 as evidence
+use docs2 as evidence
+```
+
+重复 label 按声明顺序分别渲染：
+
+```text
+[evidence]
+docs1...
+
+[evidence]
+docs2...
+```
+
+## 7. Multi-Agent Provenance
+
+Agent 调用结果应在 trace 或内部 metadata 中保留 provenance：
+
+```json
+{
+  "agent": "Planner",
+  "role": "Planner",
+  "function": "main",
+  "trace_id": "..."
+}
+```
+
+这类 metadata 不一定暴露给用户代码，但应可用于 trace 和 context renderer。
+
+用法：
+
+```agentscript
+plan = Planner(input)
+critique = Critic(plan)
+
+use plan.summary < 2k as plan
+use critique.summary < 2k as critique
+```
+
+渲染时可以结合 provenance：
+
+```text
+[plan]
+Produced by: Planner
+Role: Planner
+Output:
+...
+
+[critique]
+Produced by: Critic
+Role: Skeptical Reviewer
+Output:
+...
+```
+
+这样能表达 multi-agent 中“不同角色发言”的感觉，同时不污染 provider message role。
+
+## 8. Trace 展示
+
+Trace 同时显示 agent identity、instruction、context label、source expression 和 budget。
+
+```text
+Generate #1
+Agent:
+  name: ResearchAgent
+  role: Senior Researcher
+
+Instruction:
+  Answer using only the selected context.
+
+Selected context:
+  [user]
+  source: input.question
+  budget: none
+
+  [memory]
+  source: scratch.summary
+  budget: 2k
+
+  [evidence]
+  source: docs.summary
+  budget: 4k
+
+Output shape:
+  ok boolean
+  answer string
+```
+
+Multi-agent trace 可以显示：
+
+```text
+Agent call:
+  Planner.main
+  role: Planner
+
+Agent call:
+  Critic.main
+  role: Skeptical Reviewer
+
+Generate #3
+Agent:
+  Coordinator
+  role: Coordinator
+
+Selected context:
+  [plan]
+  produced_by: Planner
+  producer_role: Planner
+
+  [critique]
+  produced_by: Critic
+  producer_role: Skeptical Reviewer
+```
+
+## 9. 当前实现方案
+
+当前实现包括：
+
+1. `role` 和 `description` 进入每次 `generate` 的 system / identity prompt。
+2. `UseStmt` 增加可选 `label` 字段，保存 label 字面文本。
+3. Parser 支持 `use expr as label` 和 `use expr < budget as label`。
+4. Parser 将 `as` 后面的 label 保存为原始标签文本，不按表达式解析。
+5. Semantic analyzer 校验保留 label，避免和 provider role 混淆。
+6. Context builder 在 trace 和 prompt renderer 中使用 label。
+7. Agent call trace 保留 agent name、role、function 等 provenance。
+
+当前设计保持执行和上下文注入分离：
+
+```agentscript
+critique = Critic(draft)
+use critique as critique
+```
+
+## 10. 术语表
+
+```text
+provider role:
+  底层 chat message role，例如 system/user/assistant/tool。
+
+agent role:
+  agent 生成输出时使用的身份，也可作为 agent 输出的 speaker provenance。
+
+context label:
+  通过 use ... as ... 附加到 selected context 的用途标签。
+
+speaker provenance:
+  agent 调用产物携带的来源元信息，包括 agent name、role、function 和 trace id。
+
+agent transcript:
+  在 prompt 或 trace 中按 agent 来源组织的多 agent 输出展示形式。
+```
+
+## 11. 一句话总结
+
+```text
+provider role 是消息协议；
+agent role 是生成身份和发言者身份；
+context label 是上下文用途标签。
+```
+
+AgentScript 应在语言层构造 labeled context 和 agent transcript，再由 runtime 映射到底层 provider messages。

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

@@ -59,6 +59,24 @@ func run(input) {
 }
 ```
 
+This rule applies to all expression forms, including calls. It does not matter whether the callee resolves to a local function or an agent call. For example, calling another agent by name invokes that agent's `main func`, and the result is returned implicitly:
+
+```agentscript
+agent Planner {
+    main func(input) {
+        generate({ input: "Create a plan" }) -> {
+            steps list[string]
+        }
+    }
+}
+
+agent Controller {
+    func run(input) {
+        Planner(input)
+    }
+}
+```
+
 ```agentscript
 func get_result(result) {
     result.value

package/docs/en/language.md

@@ -158,6 +158,8 @@ Shapes are not a full static type system.
 use input.question
 use Requirements < 4k
 use past_lessons < 2k
+use input.question as user
+use docs.summary < 4k as evidence
 ```
 
 ### Rules
@@ -167,10 +169,24 @@ use past_lessons < 2k
 - Memory query results do not automatically enter prompts.
 - Trace events do not automatically enter prompts.
 - `use value < n` applies a context budget.
+- `use value as label` attaches a literal context label to the selected source.
+- `use value < n as label` applies the budget first, then attaches the label.
 - `llm`, `tool`, `agent`, `memory` bindings cannot be used.
 - Function bindings cannot be used.
 - `use` declarations are inherited by child scopes.
 
+### Context labels
+
+The label after `as` is literal label text. It is not an expression, is not evaluated, and does not read variables from scope.
+
+```agentscript
+use docs as evidence
+use docs.summary < 4k as retrieved evidence
+use input.question as user
+```
+
+`as evidence` labels the context section as `evidence` even if a variable named `evidence` exists. Labels organize prompt sections and trace output; they do not change provider message roles such as `system`, `user`, or `assistant`.
+
 ### Deferred evaluation
 
 `use expr < budget` declares a context source, not a snapshot. The expression is re-evaluated when `generate` builds the prompt. This means updates to a variable made after `use` but before `generate` are visible at generation time.

package/examples/changelog.as

@@ -13,8 +13,8 @@ main agent ChangelogWriter {
             path: input.diff_path
         })
 
-        use input.diff_path
-        use diff < 10k
+        use input.diff_path as diff path
+        use diff < 10k as git diff
 
         generate({ input: "Write a changelog from this git diff", limit: 1200 }) -> {
             title string

package/examples/extract.as

@@ -14,8 +14,8 @@ main agent ApiExtractor {
             timeout: 10000
         })
 
-        use input.url
-        use response < 8k
+        use input.url as endpoint
+        use response < 8k as api response
 
         generate({ input: "Extract normalized data from the API response", limit: 1200 }) -> {
             records list[json]

package/examples/review.as

@@ -22,9 +22,9 @@ main agent CodeReviewAssistant {
             max: 100
         })
 
-        use input.path
-        use todos < 4k
-        use fixmes < 4k
+        use input.path as source path
+        use todos < 4k as todo findings
+        use fixmes < 4k as fixme findings
 
         generate({ input: "Turn TODO and FIXME scan results into prioritized repair suggestions", limit: 1200 }) -> {
             summary string

package/examples/summarize.as

@@ -13,8 +13,8 @@ main agent FileSummarizer {
             path: input.path
         })
 
-        use input.path
-        use content < 8k
+        use input.path as source path
+        use content < 8k as file content
 
         generate({ input: "Summarize the file for a busy teammate", limit: 1000 }) -> {
             title string

package/examples/translate.as

@@ -17,9 +17,9 @@ main agent MarkdownTranslator {
             max: 50
         })
 
-        use input.path
-        use input.target_language
-        use files < 4k
+        use input.path as source path
+        use input.target_language as target language
+        use files < 4k as markdown files
 
         generate({ input: "Create a practical markdown translation plan", limit: 1000 }) -> {
             target_language string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rong/agentscript",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "AgentScript context engineering language runtime",
   "main": "dist/index.js",
   "bin": {