@rong/agentscript 0.1.0 → 0.1.1

package/INSTALL.md

@@ -4,18 +4,18 @@ AgentScript is distributed as an npm package and can also be run from source.
 
 ## Requirements
 
-- Node.js compatible with the runtime features used by this project.
+- Node.js >= 22.5.
 - npm.
 - Optional: Ollama, OpenAI, or Anthropic credentials when running with `--real-llm`.
 
-The current development setup uses Node.js 25 types and the SQLite memory backend uses Node's built-in `node:sqlite` module.
+The SQLite memory backend uses Node's built-in `node:sqlite` module, so Node.js 22.5 or newer is required.
 
 ## Install from npm
 
 After the package is published:
 
 ```bash
-npm install -g agentscript
+npm install -g @rong/agentscript
 agentscript examples/review.as --input '{"path":"src"}'
 ```
 
@@ -24,7 +24,7 @@ agentscript examples/review.as --input '{"path":"src"}'
 After the package is published:
 
 ```bash
-npx agentscript examples/review.as --input '{"path":"src"}'
+npx @rong/agentscript examples/review.as --input '{"path":"src"}'
 ```
 
 ## Run from source

package/README.md

@@ -1,69 +1,40 @@
 # AgentScript
 
-> **Prompt context as a first-class citizen.**  
-> `use` declares what the model sees. `generate` defines what it returns.  
+> **Agent context as code.**
+> `use` declares what the model can see.
+> `generate` defines the only LLM call site and its return shape.
 > Zero runtime dependencies. TypeScript-powered.
 
 ```agentscript
 use scratch.summary < 2k
-return generate({ input: "Answer from observations" }) {
-    return { ok boolean, text string }
+return generate({ input: "Answer from observations" }) -> {
+    ok boolean
+    text string
 }
 ```
 
-[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
-![Node >= 25](https://img.shields.io/badge/node-%3E%3D25-green)
+![Node >= 22.5](https://img.shields.io/badge/node-%3E%3D22.5-green)
 
 [中文版](./README-CN.md)
 
-LLMs are stateless by nature. Each call is a fresh start. To give an agent continuity of thought, every input must be carefully assembled — what researchers and practitioners call context engineering.
-
-After building agents with Python and TypeScript, the author kept running into the same problem: prompt context management. What data actually reaches the LLM? Where does one agent's context end and another's begin? How do you audit what the model saw?
-
-AgentScript was designed to solve this — not as a general-purpose language, nor a declarative config, nor a prompt template, but as a **DSL** that mixes imperative control flow with explicit, scope-governed context declarations.
-
-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 *what* the LLM must return. 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.
-
-The result is a language purpose-built for composing agent patterns — ReAct, Plan-and-Execute, Reflection, Multi-Agent — where prompt context is always visible, auditable, and under your control.
-
-## How it works
+## Install
 
-```mermaid
-graph LR
-    A[".as source"] --> B["Parser"]
-    B --> C["AST"]
-    C --> D["Semantic Analyzer"]
-    D --> E["Runtime"]
-    E --> F["LLM Provider<br/>(OpenAI / Anthropic / Ollama)"]
-    E --> G["Tools<br/>(Find / Grep / File / HTTP / ...)"]
-    E --> H["Memory<br/>(JSONL / SQLite)"]
-    E --> I["Trace Output"]
+```bash
+npm install -g @rong/agentscript
 ```
 
-## Agent patterns as composable primitives
-
-AgentScript doesn't hardcode agent patterns as keywords. You compose them from the same primitives:
-
-| Pattern | Tutorial | What it demonstrates |
-|---------|----------|---------------------|
-| **ReAct** | `tutorials/react.as` | Reason → Act → Observe loop with explicit context |
-| **Plan-and-Execute** | `tutorials/plan-execute.as` | Generate plan, execute steps, verify, re-plan on failure |
-| **Reflection / Self-Improvement** | `tutorials/self-improve.as` | Query past lessons → generate → reflect → persist new lessons |
-| **Multi-Agent** | `tutorials/plan-execute.as` | Independent agents with isolated context boundaries |
-
-Every pattern is explicit — which data enters the prompt, which tools each agent can use, and which output shape each LLM call must satisfy.
-
-## Install
+Then run the CLI:
 
 ```bash
-npm install -g agentscript
+agentscript --help
 ```
 
 Or run without installing:
 
 ```bash
-npx agentscript examples/review.as --input '{"path":"src"}'
+npx @rong/agentscript examples/review.as --input '{"path":"src"}'
 ```
 
 ## Quick start
@@ -96,13 +67,11 @@ main agent FileSummarizer {
         return generate({
             input: "Summarize the file for a busy teammate"
             limit: 1000
-        }) {
-            return {
-                title string
-                summary string
-                key_points list[string]
-                action_items list[string]
-            }
+        }) -> {
+            title string
+            summary string
+            key_points list[string]
+            action_items list[string]
         }
     }
 }
@@ -124,6 +93,76 @@ Expected output (with mock LLM):
 
 With `--real-llm`, the fields are populated by the model.
 
+The block after `generate` is a return schema, not ordinary object construction.
+
+## What problem it solves
+
+LLMs are stateless by nature. Each call is a fresh start. To give an agent continuity of thought, every input must be carefully assembled — what researchers and practitioners call context engineering.
+
+After building agents with Python and TypeScript, the author kept running into the same problem: prompt context management. What data actually reaches the LLM? Where does one agent's context end and another's begin? How do you audit what the model saw?
+
+## What makes AgentScript different?
+
+AgentScript is not:
+
+- a prompt template
+- a YAML config format
+- a general-purpose agent framework
+
+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 *what* the LLM must return. 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.
+
+## How it works
+
+```mermaid
+graph LR
+    A[".as source"] --> B["Parser"]
+    B --> C["AST"]
+    C --> D["Semantic Analyzer"]
+    D --> E["Runtime"]
+    E --> F["LLM Provider<br/>(OpenAI / Anthropic / Ollama)"]
+    E --> G["Tools<br/>(Find / Grep / File / HTTP / ...)"]
+    E --> H["Memory<br/>(JSONL / SQLite)"]
+    E --> I["Trace Output"]
+```
+
+## Status
+
+AgentScript is experimental.
+
+Currently implemented:
+
+- parser
+- semantic checker
+- mock runtime
+- OpenAI / Anthropic / Ollama LLM adapters
+- file and environment tools
+- JSONL and SQLite memory backends
+- trace output
+
+Planned:
+
+- stable IR
+- richer diagnostics
+- VS Code syntax support
+- package publishing hardening
+
+## Agent patterns as composable primitives
+
+AgentScript doesn't hardcode agent patterns as keywords. You compose them from the same primitives:
+
+| Pattern | Tutorial | What it demonstrates |
+|---------|----------|---------------------|
+| **ReAct** | `tutorials/react.as` | Reason → Act → Observe loop with explicit context |
+| **Plan-and-Execute** | `tutorials/plan-execute.as` | Generate plan, execute steps, verify, re-plan on failure |
+| **Reflection / Self-Improvement** | `tutorials/self-improve.as` | Query past lessons → generate → reflect → persist new lessons |
+| **Multi-Agent** | `tutorials/plan-execute.as` | Independent agents with isolated context boundaries |
+
+Every pattern is explicit — which data enters the prompt, which tools each agent can use, and which output shape each LLM call must satisfy.
+
 ## Language at a glance
 
 ```agentscript
@@ -158,12 +197,10 @@ main agent ResearchAgent {
     func answer(question, scratch) {
         use question
         use scratch.summary < 2k
-        return generate({ input: "Answer using only the observations" }) {
-            return {
-                ok boolean
-                text string
-                error string
-            }
+        return generate({ input: "Answer using only the observations" }) -> {
+            ok boolean
+            text string
+            error string
         }
     }
 }

package/dist/parser/parser.js

@@ -408,10 +408,8 @@ class Parser {
         this.consume("(");
         const options = this.parseGenerateOptions();
         this.consume(")");
-        this.consume("{");
-        this.consume("return");
+        this.consume("->");
         const returnShape = this.parseShapeObject();
-        this.consume("}");
         return {
             kind: "GenerateExpr",
             options,

package/dist/parser/tokenizer.js

@@ -40,6 +40,7 @@ const SYMBOLS = new Set([
     "=",
     "!",
     "<",
+    "-",
     "*"
 ]);
 export function tokenize(source) {
@@ -77,7 +78,7 @@ class Scanner {
             }
             if (SYMBOLS.has(char)) {
                 const twoChar = `${char}${this.peekNext()}`;
-                if (twoChar === "==" || twoChar === "!=") {
+                if (twoChar === "==" || twoChar === "!=" || twoChar === "->") {
                     this.advance();
                     this.advance();
                     tokens.push({

package/docs/cn/context-engineering.md

@@ -10,13 +10,13 @@ AgentScript 表面上有变量、函数、循环和 Agent 调用，但它的主
 
 AgentScript 的控制流服务于 prompt context 构建。
 
-普通语句负责组织数据、调用工具、调用 Agent 和更新中间状态。LLM 调用只能通过 `generate(...) { return ... }` 发生，而 `generate` 能看到的上下文必须由 `use` 显式声明。
+普通语句负责组织数据、调用工具、调用 Agent 和更新中间状态。LLM 调用只能通过 `generate(...) -> { ... }` 发生，而 `generate` 能看到的上下文必须由 `use` 显式声明。
 
 AgentScript 的核心对象是：
 
 - `Data`：普通变量、JSON、list、file import、tool observation 和 Agent 返回值。
 - `Context Source`：由 `use expr < budget` 声明的 prompt context 来源。
-- `Generation Site`：由 `generate({ input, limit, attempts, debug }) { return shape }` 声明的一次 LLM 调用。
+- `Generation Site`：由 `generate({ input, limit, attempts, debug }) -> shape` 声明的一次 LLM 调用。
 - `Boundary`：由 Agent、function 和 block scope 形成的 context 可见性边界。
 
 ## `use` 的语义
@@ -35,12 +35,10 @@ func answer(question, scratch) {
     return generate({
         input: "Answer the question using collected facts"
         limit: 800
-    }) {
-        return {
-            ok boolean
-            text string
-            error string
-        }
+    }) -> {
+        ok boolean
+        text string
+        error string
     }
 }
 ```
@@ -63,10 +61,8 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) {
-        return {
-            text string
-        }
+    return generate({ input: "Answer from scratch" }) -> {
+        text string
     }
 }
 ```
@@ -128,10 +124,8 @@ func caller(input) {
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) {
-        return {
-            ok boolean
-        }
+    return generate({ input: "Work on detail" }) -> {
+        ok boolean
     }
 }
 ```
@@ -171,10 +165,8 @@ result = Worker({
 if condition {
     temp = compute(input)
     use temp
-    result = generate({ input: "Use temp" }) {
-        return {
-            ok boolean
-        }
+    result = generate({ input: "Use temp" }) -> {
+        ok boolean
     }
 }
 ```
@@ -231,11 +223,9 @@ source label 有助于模型理解 context，也有助于人类审计。
 Instruction 层来自 `generate(...)` 参数对象中的 `input` 字段。
 
 ```agentscript
-generate({ input: "Answer the question using only collected facts" }) {
-    return {
-        ok boolean
-        text string
-    }
+generate({ input: "Answer the question using only collected facts" }) -> {
+    ok boolean
+    text string
 }
 ```
 
@@ -273,10 +263,8 @@ use scratch.summary < 2k
 return generate({
     input: "Summarize"
     limit: 500
-}) {
-    return {
-        text string
-    }
+}) -> {
+    text string
 }
 ```
 

package/docs/cn/language.md

@@ -1,6 +1,6 @@
 # AgentScript 语言参考
 
-本文档描述 AgentScript v1.0.0 的当前语言规范。
+本文档描述 AgentScript v0.1.x 的当前语言规范。
 
 ## 设计原则
 
@@ -27,11 +27,9 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) {
-            return {
-                ok boolean
-                answer string
-            }
+        return generate({ input: "Answer the question" }) -> {
+            ok boolean
+            answer string
         }
     }
 }
@@ -140,13 +138,11 @@ func careful(input) {
 Shape 用于输入校验和 `generate` 输出校验：
 
 ```agentscript
-return generate({ input: "Extract facts" }) {
-    return {
-        ok boolean
-        title string
-        items list[json]
-        meta json
-    }
+return generate({ input: "Extract facts" }) -> {
+    ok boolean
+    title string
+    items list[json]
+    meta json
 }
 ```
 
@@ -189,12 +185,10 @@ answer = generate({
     limit: 800
     attempts: 3
     debug: true
-}) {
-    return {
-        ok boolean
-        answer string
-        reason string
-    }
+}) -> {
+    ok boolean
+    answer string
+    reason string
 }
 ```
 
@@ -204,7 +198,7 @@ answer = generate({
 - `limit`：生成预算（数字或 `2k` 格式）。可选。
 - `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
-- `return { ... }` 块声明期望的输出 shape。
+- `-> { ... }` 块声明期望的输出 shape。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
@@ -371,11 +365,9 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) {
-        return {
-            ok boolean
-            answer string
-        }
+    return generate({ input: "Answer from the referenced file." }) -> {
+        ok boolean
+        answer string
     }
 }
 ```
@@ -466,7 +458,7 @@ main agent Controller {
 
 ## 非目标
 
-AgentScript v1.0.0 不包含：
+AgentScript v0.1.x 不包含：
 
 - 通用工作流引擎。
 - 通用并行执行语法。

package/docs/design-history/v0-design.md

@@ -20,7 +20,7 @@ V0 支持：
 - Agent 内函数、变量赋值、对象/列表字面量、成员访问、函数调用。
 - `model`、`role`、`description` 作用域配置。
 - `use` 上下文声明和 `< n` 上下文预算。
-- `generate({ input, limit, attempts, debug }) { return { ... } }` LLM 调用。
+- `generate({ input, limit, attempts, debug }) -> { ... }` LLM 调用。
 - `if` / `else`，`==`、`!=`、`and`、`or`、`not`。
 - `loop until condition < n` 有上限循环。
 - `repeat * n` 有上限重复执行。
@@ -56,11 +56,9 @@ main agent ResearchAgent {
     func answer(question) {
         use question
 
-        return generate({ input: "Answer the question" }) {
-            return {
-                ok boolean
-                text string
-            }
+        return generate({ input: "Answer the question" }) -> {
+            ok boolean
+            text string
         }
     }
 }
@@ -105,10 +103,8 @@ agent A {
         model Strong
         description "Use a stronger model for this function."
 
-        return generate({ input: "Answer carefully" }) {
-            return {
-                text string
-            }
+        return generate({ input: "Answer carefully" }) -> {
+            text string
         }
     }
 }
@@ -134,13 +130,11 @@ V0 运行时数据以 JSON 为核心：
 `generate` 返回 shape 使用轻量标注：
 
 ```agentscript
-return generate({ input: "Extract facts" }) {
-    return {
-        facts list[string]
-        source string
-        meta json
-        ok boolean
-    }
+return generate({ input: "Extract facts" }) -> {
+    facts list[string]
+    source string
+    meta json
+    ok boolean
 }
 ```
 
@@ -155,11 +149,9 @@ func compose(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({ input: "Answer using only the context" }) {
-        return {
-            ok boolean
-            text string
-        }
+    return generate({ input: "Answer using only the context" }) -> {
+        ok boolean
+        text string
     }
 }
 ```
@@ -175,19 +167,17 @@ func compose(question, scratch) {
 
 ## Generate
 
-`generate({ input, limit, attempts, debug }) { return { ... } }` 表示一次 LLM call。`input` 是本次 call 的最后用户指令，可以是字符串、对象或其它 JSON 值。`limit`、`attempts`、`debug` 都是可选参数。
+`generate({ input, limit, attempts, debug }) -> { ... }` 表示一次 LLM call。`input` 是本次 call 的最后用户指令，可以是字符串、对象或其它 JSON 值。`limit`、`attempts`、`debug` 都是可选参数。
 
 ```agentscript
 answer = generate({
     input: "Answer using collected facts"
     limit: 800
     attempts: 3
-}) {
-    return {
-        ok boolean
-        text string
-        error string
-    }
+}) -> {
+    ok boolean
+    text string
+    error string
 }
 ```
 
@@ -198,7 +188,7 @@ answer = generate({
 - `limit` 是本次 LLM call 的预算，支持 `800` 或 `2k` 这类 budget 字面量。
 - `attempts` 表示最多生成次数；它不是额外重试次数。
 - `debug` 是 boolean，缺省值为 `false`；为 `true` 时 runtime 将完整 prompt 打印到 stderr。
-- 块内 `return { ... }` 描述 LLM 输出 JSON shape，不会从外层函数返回。
+- `-> { ... }` 描述 LLM 输出 JSON shape，不会从外层函数返回。
 - LLM 输出会先按 shape 做有限容错转换。
 - 当输出不是 JSON 或转换后仍不符合 shape，且 `attempts > 1` 时，下一次调用会把上一次输出和错误信息附加到 `input` 后，请模型 repair。
 - provider 网络、认证、超时、模型不存在等基础设施错误不会被 repair 重试。

package/docs/design-history/v0-implement.md

@@ -1,6 +1,6 @@
 # AgentScript V0 Implement
 
-本文档是 V0 阶段的历史实现快照。语言设计见 `v0-design.md`。当前 v1.0.0 的实现入口和模块概览见 `../en/language.md` 与 `../cn/language.md`。
+本文档是 V0 阶段的历史实现快照。语言设计见 `v0-design.md`。当前 v0.1.x 的实现入口和模块概览见 `../en/language.md` 与 `../cn/language.md`。
 
 ## 执行管线
 
@@ -92,7 +92,7 @@ V0 AST 节点：
 - `main agent { ... }` 映射为匿名入口 Agent，内部名 `__main_agent`。
 - `main func(input) { ... }` 映射为匿名入口函数，内部名 `__main`。
 - `AgentName(input)` 是普通 `CallExpr`，语义和运行时把它解析为目标 Agent 的 `main func` 调用。
-- `generate({ input: "...", limit: 500 }) { return { ... } }` 把生成预算保存在 `GenerateExpr` options 中。
+- `generate({ input: "...", limit: 500 }) -> { ... }` 把生成预算保存在 `GenerateExpr` options 中。
 - `use value < 2k` 的预算在 `UseStmt` 上。
 - `loop until done < 6` 的 `< 6` 是循环上限，不是比较表达式。
 
@@ -198,7 +198,7 @@ V0 的预算裁剪按字符数实现：`2k` 约等于 2000 字符。这是当前
 
 ```ts
 interface ToolProvider {
-  call(request: ToolCallRequest): Promise<RuntimeValue>;
+    call(request: ToolCallRequest): Promise<RuntimeValue>;
 }
 ```
 

package/docs/design-history/v1-design.md

@@ -113,10 +113,8 @@ for item in list < n {
 V1 不需要专门的 `plan` 类型。推荐结构：
 
 ```agentscript
-return generate({ input: "Create a short executable plan" }) {
-    return {
-        steps list[json]
-    }
+return generate({ input: "Create a short executable plan" }) -> {
+    steps list[json]
 }
 ```
 
@@ -280,11 +278,9 @@ func answer(input) {
     use Requirements < 4k
     use input.question
 
-    return generate({ input: "Answer from the referenced file" }) {
-        return {
-            ok boolean
-            text string
-        }
+    return generate({ input: "Answer from the referenced file" }) -> {
+        ok boolean
+        text string
     }
 }
 ```

package/docs/design-history/v2-design.md

@@ -213,12 +213,10 @@ agent Reflector {
         return generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
-        }) {
-            return {
-                insight string
-                mistake string
-                next_rule string
-            }
+        }) -> {
+            insight string
+            mistake string
+            next_rule string
         }
     }
 }
@@ -270,12 +268,10 @@ main agent Learner {
         result = generate({
             input: "Answer the goal using relevant past lessons.",
             attempts: 3
-        }) {
-            return {
-                ok boolean
-                answer string
-                reason string
-            }
+        }) -> {
+            ok boolean
+            answer string
+            reason string
         }
 
         reflection = reflect({
@@ -299,10 +295,8 @@ main agent Learner {
         return generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
-        }) {
-            return {
-                insight string
-            }
+        }) -> {
+            insight string
         }
     }
 }

package/docs/en/context-engineering.md

@@ -8,13 +8,13 @@ AgentScript has variables, functions, loops, and agent calls, but its primary pu
 
 AgentScript's control flow serves prompt context construction.
 
-Ordinary statements organize data, call tools, call agents, and update intermediate state. LLM calls happen only through `generate(...) { return ... }`, and the context visible to `generate` must be declared explicitly with `use`.
+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`.
 
 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 }) { return shape }`.
+- **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`
@@ -33,12 +33,10 @@ func answer(question, scratch) {
     return generate({
         input: "Answer the question using collected facts"
         limit: 800
-    }) {
-        return {
-            ok boolean
-            text string
-            error string
-        }
+    }) -> {
+        ok boolean
+        text string
+        error string
     }
 }
 ```
@@ -57,10 +55,8 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) {
-        return {
-            text string
-        }
+    return generate({ input: "Answer from scratch" }) -> {
+        text string
     }
 }
 ```
@@ -108,10 +104,8 @@ func caller(input) {
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) {
-        return {
-            ok boolean
-        }
+    return generate({ input: "Work on detail" }) -> {
+        ok boolean
     }
 }
 ```
@@ -145,10 +139,8 @@ Blocks (`if`, `repeat`, `loop`, `for`) create child scopes. `use` declarations i
 if condition {
     temp = compute(input)
     use temp
-    result = generate({ input: "Use temp" }) {
-        return {
-            ok boolean
-        }
+    result = generate({ input: "Use temp" }) -> {
+        ok boolean
     }
 }
 ```
@@ -205,11 +197,9 @@ Source labels help models understand context and help humans audit prompts.
 Comes from the `input` field of `generate(...)` options.
 
 ```agentscript
-generate({ input: "Answer the question using only collected facts" }) {
-    return {
-        ok boolean
-        text string
-    }
+generate({ input: "Answer the question using only collected facts" }) -> {
+    ok boolean
+    text string
 }
 ```
 

package/docs/en/language.md

@@ -1,6 +1,6 @@
 # AgentScript Language
 
-This document describes the current AgentScript v1.0.0 language.
+This document describes AgentScript v0.1.x.
 
 ## Design principles
 
@@ -27,11 +27,9 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) {
-            return {
-                ok boolean
-                answer string
-            }
+        return generate({ input: "Answer the question" }) -> {
+            ok boolean
+            answer string
         }
     }
 }
@@ -140,13 +138,11 @@ Runtime values are JSON-oriented:
 Shapes are used for input validation and `generate` output validation:
 
 ```agentscript
-return generate({ input: "Extract facts" }) {
-    return {
-        ok boolean
-        title string
-        items list[json]
-        meta json
-    }
+return generate({ input: "Extract facts" }) -> {
+    ok boolean
+    title string
+    items list[json]
+    meta json
 }
 ```
 
@@ -189,12 +185,10 @@ answer = generate({
     limit: 800
     attempts: 3
     debug: true
-}) {
-    return {
-        ok boolean
-        answer string
-        reason string
-    }
+}) -> {
+    ok boolean
+    answer string
+    reason string
 }
 ```
 
@@ -204,7 +198,7 @@ answer = generate({
 - `limit` is the generation budget (number or `2k` style). Optional.
 - `attempts` controls retry for JSON parse errors or shape mismatch. Optional, defaults to 1.
 - `debug` prints the full prompt to stderr. Optional, defaults to false.
-- The `return { ... }` block declares the expected output shape.
+- The `-> { ... }` block declares the expected output shape.
 - Provider errors (auth, network, timeout, missing model) fail directly without retry.
 - Shape validation includes coercion (e.g. `"true"` -> `true`, `"42"` -> `42`).
 
@@ -371,11 +365,9 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) {
-        return {
-            ok boolean
-            answer string
-        }
+    return generate({ input: "Answer from the referenced file." }) -> {
+        ok boolean
+        answer string
     }
 }
 ```
@@ -466,7 +458,7 @@ The interpreter is a tree-walking evaluator. There is no IR, bytecode, or compil
 
 ## Non-goals
 
-AgentScript v1.0.0 does not provide:
+AgentScript v0.1.x does not provide:
 
 - A general workflow engine.
 - General parallel execution syntax.

package/examples/changelog.as

@@ -16,14 +16,12 @@ main agent ChangelogWriter {
         use input.diff_path
         use diff < 10k
 
-        return generate({ input: "Write a changelog from this git diff", limit: 1200 }) {
-            return {
-                title string
-                highlights list[string]
-                breaking_changes list[string]
-                fixes list[string]
-                notes string
-            }
+        return generate({ input: "Write a changelog from this git diff", limit: 1200 }) -> {
+            title string
+            highlights list[string]
+            breaking_changes list[string]
+            fixes list[string]
+            notes string
         }
     }
 }

package/examples/extract.as

@@ -17,13 +17,11 @@ main agent ApiExtractor {
         use input.url
         use response < 8k
 
-        return generate({ input: "Extract normalized data from the API response", limit: 1200 }) {
-            return {
-                records list[json]
-                fields list[string]
-                warnings list[string]
-                summary string
-            }
+        return generate({ input: "Extract normalized data from the API response", limit: 1200 }) -> {
+            records list[json]
+            fields list[string]
+            warnings list[string]
+            summary string
         }
     }
 }

package/examples/review.as

@@ -26,13 +26,11 @@ main agent CodeReviewAssistant {
         use todos < 4k
         use fixmes < 4k
 
-        return generate({ input: "Turn TODO and FIXME scan results into prioritized repair suggestions", limit: 1200 }) {
-            return {
-                summary string
-                findings list[string]
-                suggested_fixes list[string]
-                next_steps list[string]
-            }
+        return generate({ input: "Turn TODO and FIXME scan results into prioritized repair suggestions", limit: 1200 }) -> {
+            summary string
+            findings list[string]
+            suggested_fixes list[string]
+            next_steps list[string]
         }
     }
 }

package/examples/summarize.as

@@ -16,13 +16,11 @@ main agent FileSummarizer {
         use input.path
         use content < 8k
 
-        return generate({ input: "Summarize the file for a busy teammate", limit: 1000 }) {
-            return {
-                title string
-                summary string
-                key_points list[string]
-                action_items list[string]
-            }
+        return generate({ input: "Summarize the file for a busy teammate", limit: 1000 }) -> {
+            title string
+            summary string
+            key_points list[string]
+            action_items list[string]
         }
     }
 }

package/examples/translate.as

@@ -21,13 +21,11 @@ main agent MarkdownTranslator {
         use input.target_language
         use files < 4k
 
-        return generate({ input: "Create a practical markdown translation plan", limit: 1000 }) {
-            return {
-                target_language string
-                files list[string]
-                glossary_notes list[string]
-                instructions string
-            }
+        return generate({ input: "Create a practical markdown translation plan", limit: 1000 }) -> {
+            target_language string
+            files list[string]
+            glossary_notes list[string]
+            instructions string
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rong/agentscript",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AgentScript context engineering language runtime",
   "main": "dist/index.js",
   "bin": {
@@ -47,9 +47,17 @@
   ],
   "author": "Rong Zhou",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rongzhou/agentscript.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rongzhou/agentscript/issues"
+  },
+  "homepage": "https://github.com/rongzhou/agentscript#readme",
   "type": "module",
   "engines": {
-    "node": ">=25"
+    "node": ">=22.5"
   },
   "devDependencies": {
     "@types/node": "^25.6.2",

package/tutorials/cli.as

@@ -12,11 +12,9 @@ main agent {
         use input.name
         use input.request
 
-        return generate({ input: "Reply to the CLI user by name", limit: 300 }) {
-            return {
-                ok boolean
-                message string
-            }
+        return generate({ input: "Reply to the CLI user by name", limit: 300 }) -> {
+            ok boolean
+            message string
         }
     }
 }

package/tutorials/plan-execute.as

@@ -75,12 +75,10 @@ main agent PlanAndExecute {
         use goal
         use results.summary < 2k
 
-        return generate({ input: "Create the final answer from executed steps", limit: 800 }) {
-            return {
-                ok boolean
-                text string
-                error string
-            }
+        return generate({ input: "Create the final answer from executed steps", limit: 800 }) -> {
+            ok boolean
+            text string
+            error string
         }
     }
 }
@@ -95,12 +93,10 @@ agent Planner {
         use input.problem
         use input.previous < 1k
 
-        return generate({ input: "Create a three step plan", limit: 600 }) {
-            return {
-                step1 string
-                step2 string
-                step3 string
-            }
+        return generate({ input: "Create a three step plan", limit: 600 }) -> {
+            step1 string
+            step2 string
+            step3 string
         }
     }
 }
@@ -125,12 +121,10 @@ agent Executor {
 
         use observation
 
-        return generate({ input: "Report the result of this step", limit: 500 }) {
-            return {
-                ok boolean
-                output json
-                error string
-            }
+        return generate({ input: "Report the result of this step", limit: 500 }) -> {
+            ok boolean
+            output json
+            error string
         }
     }
 }
@@ -145,11 +139,9 @@ agent Verifier {
         use input.step
         use input.result
 
-        return generate({ input: "Verify this step result", limit: 300 }) {
-            return {
-                ok boolean
-                reason string
-            }
+        return generate({ input: "Verify this step result", limit: 300 }) -> {
+            ok boolean
+            reason string
         }
     }
 }

package/tutorials/react.as

@@ -32,11 +32,9 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 1k
 
-        return generate({ input: "Choose the next search focus", limit: 300 }) {
-            return {
-                focus string
-                why string
-            }
+        return generate({ input: "Choose the next search focus", limit: 300 }) -> {
+            focus string
+            why string
         }
     }
 
@@ -62,11 +60,9 @@ main agent ResearchAgent {
 
         use raw
 
-        return generate({ input: "Summarize the useful observation", limit: 400 }) {
-            return {
-                facts list[string]
-                source string
-            }
+        return generate({ input: "Summarize the useful observation", limit: 400 }) -> {
+            facts list[string]
+            source string
         }
     }
 
@@ -74,10 +70,8 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 1k
 
-        verdict = generate({ input: "Decide whether the observations are enough", limit: 200 }) {
-            return {
-                done boolean
-            }
+        verdict = generate({ input: "Decide whether the observations are enough", limit: 200 }) -> {
+            done boolean
         }
 
         return verdict.done
@@ -87,12 +81,10 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 2k
 
-        return generate({ input: "Answer using only the observations", limit: 800 }) {
-            return {
-                ok boolean
-                text string
-                error string
-            }
+        return generate({ input: "Answer using only the observations", limit: 800 }) -> {
+            ok boolean
+            text string
+            error string
         }
     }
 }

package/tutorials/self-improve.as

@@ -21,12 +21,10 @@ main agent SelfImprover {
         result = generate({
             input: "Answer the goal using any relevant lessons.",
             attempts: 3
-        }) {
-            return {
-                ok boolean
-                answer string
-                reason string
-            }
+        }) -> {
+            ok boolean
+            answer string
+            reason string
         }
 
         lesson = reflect({
@@ -51,10 +49,8 @@ main agent SelfImprover {
         return generate({
             input: "Extract one durable lesson that could improve a future run.",
             attempts: 3
-        }) {
-            return {
-                insight string
-            }
+        }) -> {
+            insight string
         }
     }
 }