@rong/agentscript 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to AgentScript will be documented in this file.
 
+## 0.1.5 - 2026-05-09
+
+### Changed
+
+- Switched context budgets from `use expr < budget` to `use expr max budget`.
+- Switched loop and for-in iteration limits to `max` syntax.
+- Restored `<` as an ordinary numeric comparison operator.
+- Required comma separators between object literal fields.
+- Updated current docs, examples, tutorials, fixtures, and tests for the new syntax.
+
 ## 0.1.4 - 2026-05-08
 
 ### Added

package/README.md

@@ -6,8 +6,10 @@
 > Zero runtime dependencies. TypeScript-powered.
 
 ```agentscript
-use scratch.summary < 2k as observations
-generate({ input: "Answer from observations" }) -> {
+use scratch.summary max 2k as observations
+generate({
+    input: "Answer from observations"
+}) -> {
     ok boolean
     text string
 }
@@ -60,12 +62,14 @@ main agent FileSummarizer {
     description "Read one local file and produce a useful structured summary."
 
     main func(input { path string }) {
-        content = File.read({ path: input.path })
+        content = File.read({
+            path: input.path
+        })
         use input.path as source path
-        use content < 8k as file content
+        use content max 8k as file content
 
         generate({
-            input: "Summarize the file for a busy teammate"
+            input: "Summarize the file for a busy teammate",
             max_output: 1000
         }) -> {
             title string
@@ -181,10 +185,10 @@ main agent ResearchAgent {
         use input.question as user question
 
         scratch = []
-        use scratch.summary < 2k as observations
+        use scratch.summary max 2k as observations
 
         done = false
-        loop until done < 6 {
+        loop until done max 6 {
             thought = reason(input.question, scratch)
             obs = Search.search(thought.focus)
             scratch.add(obs)
@@ -196,8 +200,10 @@ main agent ResearchAgent {
 
     func answer(question, scratch) {
         use question as user question
-        use scratch.summary < 2k as observations
-        generate({ input: "Answer using only the observations" }) -> {
+        use scratch.summary max 2k as observations
+        generate({
+            input: "Answer using only the observations"
+        }) -> {
             ok boolean
             text string
             error string
@@ -281,4 +287,4 @@ Zero runtime dependencies. Built with TypeScript.
 
 ## License
 
-MIT
+MIT

package/dist/parser/parser.js

@@ -175,7 +175,7 @@ class Parser {
     parseUse() {
         const start = this.consume("use").range.start;
         const value = this.parseLogicalOr();
-        const budget = this.match("<") ? this.parseBudget() : undefined;
+        const budget = this.match("max") ? this.parseBudget() : undefined;
         const label = this.match("as") ? this.parseUseLabel() : undefined;
         return {
             kind: "UseStmt",
@@ -228,7 +228,7 @@ class Parser {
         const item = this.consumeIdentifier("Expected for item name");
         this.consume("in");
         const iterable = this.parseLogicalOr();
-        this.consume("<");
+        this.consume("max");
         const maxIterations = this.parsePositiveInteger("Expected for iteration count");
         const body = this.parseBlock();
         return {
@@ -245,7 +245,7 @@ class Parser {
         const start = this.consume("loop").range.start;
         this.consume("until");
         const condition = this.parseLogicalOr();
-        this.consume("<");
+        this.consume("max");
         const maxIterations = this.parsePositiveInteger("Expected loop iteration count");
         const body = this.parseBlock();
         return {
@@ -299,7 +299,10 @@ class Parser {
         return this.parseBinaryExpression(() => this.parseEquality(), "and");
     }
     parseEquality() {
-        return this.parseBinaryExpression(() => this.parseUnary(), "==", "!=");
+        return this.parseBinaryExpression(() => this.parseComparison(), "==", "!=");
+    }
+    parseComparison() {
+        return this.parseBinaryExpression(() => this.parseUnary(), "<");
     }
     parseBinaryExpression(parseOperand, ...operators) {
         let expr = parseOperand();
@@ -481,7 +484,7 @@ class Parser {
             else if (key === "debug" && value.kind === "BooleanExpr") {
                 debug = value;
             }
-            this.match(",");
+            this.consumePropertySeparator("}");
         }
         this.consume("}");
         return {
@@ -511,7 +514,7 @@ class Parser {
                 value,
                 range: { start: propStart, end: value.range.end }
             });
-            this.match(",");
+            this.consumePropertySeparator("}");
         }
         this.consume("}");
         return {
@@ -520,6 +523,11 @@ class Parser {
             range: { start, end: this.previous().range.end }
         };
     }
+    consumePropertySeparator(terminator) {
+        if (this.check(terminator))
+            return;
+        this.consume(",");
+    }
     parseList() {
         const start = this.consume("[").range.start;
         const items = this.parseCommaSeparatedUntil("]", () => this.parseExpression());

package/dist/parser/tokenizer.js

@@ -25,7 +25,8 @@ const KEYWORDS = new Set([
     "number",
     "boolean",
     "json",
-    "list"
+    "list",
+    "max"
 ]);
 const SYMBOLS = new Set([
     "{",

package/dist/runtime/evaluator.js

@@ -97,8 +97,16 @@ export class Evaluator {
                 return this.valuesEqual(await this.evaluate(expr.left, scope), await this.evaluate(expr.right, scope));
             case "!=":
                 return !this.valuesEqual(await this.evaluate(expr.left, scope), await this.evaluate(expr.right, scope));
+            case "<":
+                return this.evaluateLessThan(await this.evaluate(expr.left, scope), await this.evaluate(expr.right, scope), expr.range);
         }
     }
+    evaluateLessThan(left, right, range) {
+        if (typeof left !== "number" || typeof right !== "number") {
+            throw new RuntimeError("operator '<' requires number operands", range);
+        }
+        return left < right;
+    }
     valuesEqual(left, right) {
         return runtimeValuesEqual(left, right);
     }

package/docs/cn/context-engineering.md

@@ -67,7 +67,7 @@ Agent 调用形成更强的边界。被调用 Agent 不会看到 caller 的 prom
 
 ```agentscript
 result = Worker({
-    goal: input.goal
+    goal: input.goal,
     previous: results.summary
 })
 ```

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

@@ -47,8 +47,8 @@ agent 调用
 变量引用
 字段访问
 索引访问
-object literal
-list literal
+对象字面量
+列表字面量
 ```
 
 例如：
@@ -175,10 +175,10 @@ return none
 
 ```agentscript
 func summarize(content) {
-    use content < 8k
+    use content max 8k
 
     generate({
-        input: "Summarize the content"
+        input: "Summarize the content",
         max_output: 1000
     }) -> {
         title string

package/docs/cn/generate.md

@@ -21,12 +21,12 @@ generate({ input: "Answer using the selected context." }) -> {
 
 ```agentscript
 generate({
-    input: "Classify the issue"
-    max_output: 300
-    attempts: 2
-    temperature: 0.2
-    think: "medium"
-    strict: true
+    input: "Classify the issue",
+    max_output: 300,
+    attempts: 2,
+    temperature: 0.2,
+    think: "medium",
+    strict: true,
     debug: false
 }) -> {
     category string
@@ -40,7 +40,7 @@ generate({
 generate({ input: "Draft a response." })
 ```
 
-没有声明 shape 时，runtime 不应注入 schema，也不应要求 provider 返回结构化 JSON。
+没有声明 shape 时，runtime 不应注入 schema，也不应要求 provider 返回结构化 JSON。自由形式的 `generate` 是允许的，但不推荐用于 agent workflow；优先声明明确的输出 shape，便于 retry、validation、trace 和下游 agent 调用保持可审计。
 
 ## 配置字段
 
@@ -110,7 +110,7 @@ Selected context 来自可见的 `use` 声明：
 
 ```agentscript
 use input.question as user question
-use scratch.summary < 2k as observations
+use scratch.summary max 2k as observations
 ```
 
 渲染出的 prompt section 可以是：
@@ -162,7 +162,7 @@ Runtime 会在可能时请求 provider 返回结构化输出，并校验返回
 
 ```agentscript
 generate({
-    input: "Answer briefly"
+    input: "Answer briefly",
     max_output: 300
 }) -> {
     answer string
@@ -178,10 +178,10 @@ max_output = provider-side generation budget requested by AgentScript
 它和 `use` 的输入上下文预算分开：
 
 ```agentscript
-use docs.summary < 4k
+use docs.summary max 4k
 
 generate({
-    input: "Answer from the selected docs"
+    input: "Answer from the selected docs",
     max_output: 800
 }) -> {
     answer string
@@ -191,18 +191,18 @@ generate({
 区别：
 
 ```text
-use ... < 4k       = 输入上下文预算
+use ... max 4k       = 输入上下文预算
 max_output: 800    = 输出生成预算
 ```
 
 ## `attempts`
 
-`attempts` 控制结构化输出失败时的重试次数。
+`attempts` 控制 runtime 获取有效结构化结果的尝试次数。`attempts` 是最大总尝试次数，包含第一次尝试。
 
 ```agentscript
 generate({
-    input: "Extract metadata"
-    max_output: 500
+    input: "Extract metadata",
+    max_output: 500,
     attempts: 3
 }) -> {
     title string
@@ -242,8 +242,8 @@ attempts: 1
 
 ```agentscript
 generate({
-    input: "Brainstorm alternatives"
-    max_output: 1000
+    input: "Brainstorm alternatives",
+    max_output: 1000,
     temperature: 0.7
 }) -> {
     ideas list[string]
@@ -253,8 +253,8 @@ generate({
 语义：
 
 ```text
-If supported by the selected provider/model, pass through as sampling temperature.
-If unsupported, adapter may ignore, warn, or fail according to capability policy.
+如果选中的 provider/model 支持，则作为 sampling temperature 透传。
+如果不支持，adapter 可以按照 capability policy 选择 ignore、warn 或 fail。
 ```
 
 ## `think`
@@ -264,11 +264,11 @@ If unsupported, adapter may ignore, warn, or fail according to capability policy
 推荐支持：
 
 ```agentscript
-think: false
-think: true
-think: "auto"
-think: "low"
-think: "medium"
+think: false,
+think: true,
+think: "auto",
+think: "low",
+think: "medium",
 think: "high"
 ```
 
@@ -287,8 +287,8 @@ true      请求 provider 默认 thinking/reasoning 模式
 
 ```agentscript
 generate({
-    input: "Analyze the tradeoffs"
-    max_output: 1200
+    input: "Analyze the tradeoffs",
+    max_output: 1200,
     think: "high"
 }) -> {
     decision string
@@ -297,20 +297,16 @@ generate({
 }
 ```
 
-`think` 是 provider/model capability hint，不是所有模型都保证支持。
+`think` 是 provider/model capability hint，不是所有模型都保证支持。如果不支持，adapter 可以按照 capability policy 选择 ignore、warn 或 fail。
 
-如果 provider 不支持，runtime 可按策略处理：
+## Provider hint 的 capability policy
 
-```text
-ignore
-warn
-fail
-```
+`temperature` 和 `think` 都是 provider/model capability hint。不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore。
 
-默认建议：
+Adapter 可以按照 runtime capability policy 对不支持的 hint 选择 ignore、warn 或 fail，但文档中的默认语义统一为：
 
 ```text
-warn in debug mode, otherwise ignore
+不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore
 ```
 
 ## `strict`
@@ -319,8 +315,8 @@ warn in debug mode, otherwise ignore
 
 ```agentscript
 generate({
-    input: "Classify the issue"
-    max_output: 300
+    input: "Classify the issue",
+    max_output: 300,
     strict: true
 }) -> {
     category string
@@ -377,8 +373,8 @@ strict 是 AgentScript runtime 对输出契约的控制。
 
 ```agentscript
 generate({
-    input: "Answer the question"
-    max_output: 800
+    input: "Answer the question",
+    max_output: 800,
     debug: true
 }) -> {
     answer string

package/docs/cn/language.md

@@ -150,16 +150,18 @@ generate({ input: "Extract facts" }) -> {
 
 Shape 不是完整的静态类型系统。
 
+对象字面量使用 JSON-like 语法：字段写作 `key: value`，多字段之间必须用逗号分隔。
+
 ## 显式上下文（`use`）
 
 `use` 选择在当前作用域及其子作用域中，后续 `generate` 可以包含哪些变量的值。
 
 ```agentscript
 use input.question
-use Requirements < 4k
-use past_lessons < 2k
+use Requirements max 4k
+use past_lessons max 2k
 use input.question as user
-use docs.summary < 4k as evidence
+use docs.summary max 4k as evidence
 ```
 
 ### 规则
@@ -168,9 +170,9 @@ use docs.summary < 4k as evidence
 - 工具输出不会自动进入 prompt。
 - Memory 查询结果不会自动进入 prompt。
 - Trace 事件不会自动进入 prompt。
-- `use value < n` 应用上下文预算。
+- `use value max n` 应用上下文预算。
 - `use value as label` 为选中的 context source 附加字面标签。
-- `use value < n as label` 先应用预算，再附加标签。
+- `use value max n as label` 先应用预算，再附加标签。
 - `llm`、`tool`、`agent`、`memory` 绑定不能被 `use`。
 - 函数绑定不能被 `use`。
 - `use` 声明被子作用域继承。
@@ -181,7 +183,7 @@ use docs.summary < 4k as evidence
 
 ```agentscript
 use docs as evidence
-use docs.summary < 4k as retrieved evidence
+use docs.summary max 4k as retrieved evidence
 use input.question as user
 ```
 
@@ -189,7 +191,7 @@ use input.question as user
 
 ### 延迟求值
 
-`use expr < budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。
+`use expr max budget` 声明的是 context source，而不是当前值的快照。当 `generate` 构建 prompt 时，表达式会被重新求值。这意味着在 `use` 之后、`generate` 之前对变量的修改在生成时刻是可见的。
 
 完整设计语义见 [`use ... as ...`](./use-as.md)。
 
@@ -199,9 +201,9 @@ use input.question as user
 
 ```agentscript
 answer = generate({
-    input: "Answer using the selected context."
-    max_output: 800
-    attempts: 3
+    input: "Answer using the selected context.",
+    max_output: 800,
+    attempts: 3,
     debug: true
 }) -> {
     ok boolean
@@ -214,13 +216,13 @@ answer = generate({
 
 - `input`：每次生成的指令。必填。
 - `max_output`：输出生成预算（数字或 `2k` 格式）。可选。
-- `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
-- `temperature`：provider sampling hint。可选。
-- `think`：provider/model reasoning hint。可选。
+- `attempts`：JSON 解析失败或 shape 不匹配时的尝试次数。它是包含第一次调用在内的最大总尝试次数。可选，默认 1。
+- `temperature`：provider sampling hint。可选。不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore。
+- `think`：provider/model reasoning hint。可选。不支持的 provider hint 默认在 debug mode 下 warn，否则 ignore。
 - `strict`：控制 shape validation 是否严格。可选，默认 false。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
 - 可选的 `-> { ... }` 块声明期望的输出 shape。
-- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。
+- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。自由形式的 `generate` 是允许的，但不推荐用于 agent workflow。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
@@ -238,14 +240,14 @@ if answer.ok and not input.dry_run {
 }
 ```
 
-支持的运算符：`==`、`!=`、`and`、`or`、`not`。`<` 不是通用比较运算符——它只能用于预算和循环上限。
+支持的运算符：`==`、`!=`、`<`、`and`、`or`、`not`。Context budget 和循环上限使用 `max`，因此 `<` 恢复为类似 `==` 的普通比较运算符。
 
 ### Loop until
 
 ```agentscript
 done = false
 
-loop until done < 6 {
+loop until done max 6 {
     observation = observe(input)
     done = observation.ok
 }
@@ -269,7 +271,7 @@ repeat * 3 {
 ### For in
 
 ```agentscript
-for step in plan.steps < 12 {
+for step in plan.steps max 12 {
     result = Executor(step)
     results.add(result)
 }
@@ -289,7 +291,7 @@ summary = items.summary
 - `list[index]` 只读。index 必须是非负整数。
 - `list.add(value)` 修改原列表。恰好接受一个参数。
 - `.length` 返回列表长度。
-- `.summary` 返回列表的 JSON-safe 运行时视图。它不是 LLM 生成的摘要，也不是语义压缩；如果需要控制 prompt 大小，应通过 `use scratch.summary < 2k` 这类显式 context budget 裁剪。
+- `.summary` 返回列表的 JSON-safe 运行时视图。它不是 LLM 生成的摘要，也不是语义压缩；如果需要控制 prompt 大小，应通过 `use scratch.summary max 2k` 这类显式 context budget 裁剪。
 
 ## 工具
 
@@ -307,9 +309,9 @@ import tool Http from "https://api.example.com"
 
 ```agentscript
 files = Find.run({
-    path: "."
-    name: "*.ts"
-    type: "file"
+    path: ".",
+    name: "*.ts",
+    type: "file",
     max: 50
 })
 ```
@@ -318,9 +320,9 @@ files = Find.run({
 
 ```agentscript
 matches = Grep.run({
-    path: "src"
-    pattern: "TODO"
-    include: "*.ts"
+    path: "src",
+    pattern: "TODO",
+    include: "*.ts",
     max: 100
 })
 ```
@@ -329,8 +331,8 @@ matches = Grep.run({
 
 ```agentscript
 lines = Sed.run({
-    path: "src/main.as"
-    start: 1
+    path: "src/main.as",
+    start: 1,
     max: 20
 })
 ```
@@ -338,10 +340,21 @@ lines = Sed.run({
 ### File
 
 ```agentscript
-content = File.read({ path: "README.md" })
-entries = File.list({ path: "src" })
-result = File.write({ path: "output.md", content: "# Result" })
-result = File.patch({ path: "file.as", search: "old", replace: "new" })
+content = File.read({
+    path: "README.md"
+})
+entries = File.list({
+    path: "src"
+})
+result = File.write({
+    path: "output.md",
+    content: "# Result"
+})
+result = File.patch({
+    path: "file.as",
+    search: "old",
+    replace: "new"
+})
 result = File.undo(effects)
 ```
 
@@ -350,14 +363,24 @@ result = File.undo(effects)
 ### Env
 
 ```agentscript
-home = Env.get({ name: "HOME" })
+home = Env.get({
+    name: "HOME"
+})
 ```
 
 ### Http
 
 ```agentscript
-response = Http.get({ url: "/api/data", headers: { Authorization: "Bearer ..." }, timeout: 10000 })
-response = Http.post({ url: "/api/submit", body: { key: "value" }, timeout: 10000 })
+response = Http.get({
+    url: "/api/data",
+    headers: { Authorization: "Bearer ..." },
+    timeout: 10000
+})
+response = Http.post({
+    url: "/api/submit",
+    body: { key: "value" },
+    timeout: 10000
+})
 ```
 
 HTTP 请求限制在 import URI 的 origin 内。
@@ -387,7 +410,7 @@ import file Requirements from "./requirements.md"
 import file Config from "./config.json"
 
 func answer(input) {
-    use Requirements < 4k
+    use Requirements max 4k
     use Config
     generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
@@ -402,18 +425,18 @@ func answer(input) {
 
 ```agentscript
 Lessons.add({
-    kind: "lesson"
-    text: reflection.insight
+    kind: "lesson",
+    text: reflection.insight,
     goal: input.goal
 })
 
 past = Lessons.query({
-    kind: "lesson"
-    text: input.goal
+    kind: "lesson",
+    text: input.goal,
     limit: 5
 })
 
-use past < 2k
+use past max 2k
 ```
 
 ### 规则
@@ -437,8 +460,11 @@ main agent Controller {
     main func(input) {
         plan = Planner(input)
         results = []
-        for step in plan.steps < 10 {
-            result = Executor({ goal: input.goal, step: step })
+        for step in plan.steps max 10 {
+            result = Executor({
+                goal: input.goal,
+                step: step
+            })
             results.add(result)
         }
         results.summary