@rong/agentscript 0.1.0 → 0.1.2

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 optional output shape.
 > Zero runtime dependencies. TypeScript-powered.
 
 ```agentscript
 use scratch.summary < 2k
-return generate({ input: "Answer from observations" }) {
-    return { ok boolean, text string }
+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
@@ -93,16 +64,14 @@ main agent FileSummarizer {
         use input.path
         use content < 8k
 
-        return generate({
+        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 optional block after `generate` is an output 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 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
+
+```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 when one is declared.
+
 ## Language at a glance
 
 ```agentscript
@@ -152,18 +191,16 @@ main agent ResearchAgent {
             done = enough(input.question, scratch)
         }
 
-        return answer(input.question, scratch)
+        answer(input.question, scratch)
     }
 
     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
-            }
+        generate({ input: "Answer using only the observations" }) -> {
+            ok boolean
+            text string
+            error string
         }
     }
 }
@@ -172,10 +209,11 @@ main agent ResearchAgent {
 ## Key ideas
 
 1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d
-2. **`generate` is the only LLM call site** — with a required input instruction and a return shape
-3. **Scope is context boundary** — functions, agents, and blocks isolate prompt visibility
-4. **Tools, memory, and files are imported resources** — with auditable access
-5. **Trace is built in** — every `generate` and `use` is recorded for debugging
+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
+5. **Tools, memory, and files are imported resources** — with auditable access
+6. **Trace is built in** — every `generate` and `use` is recorded for debugging
 
 ## Why not just Python or TypeScript?
 

package/dist/parser/parser.js

@@ -408,10 +408,7 @@ class Parser {
         this.consume("(");
         const options = this.parseGenerateOptions();
         this.consume(")");
-        this.consume("{");
-        this.consume("return");
-        const returnShape = this.parseShapeObject();
-        this.consume("}");
+        const returnShape = this.match("->") ? this.parseShapeObject() : undefined;
         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/dist/providers/llm/anthropic.js

@@ -19,7 +19,8 @@ export async function callAnthropic(request, parsed, options, fetchImpl, timeout
         "x-api-key": apiKey,
         "anthropic-version": "2023-06-01",
     });
-    return parseJsonText(readAnthropicText(response));
+    const text = readAnthropicText(response);
+    return request.returnShape ? parseJsonText(text) : text;
 }
 function readAnthropicText(value) {
     if (!value || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.content)) {

package/dist/providers/llm/ollama.js

@@ -4,16 +4,19 @@ export async function callOllama(request, parsed, fetchImpl, timeoutMs, baseUrl)
         model: parsed.model,
         stream: false,
         think: false,
-        format: request.builtContext.returnSchema,
         messages: [
             { role: "system", content: request.builtContext.system },
             { role: "user", content: request.builtContext.finalUserMessage },
         ],
     };
+    if (request.builtContext.returnSchema) {
+        body.format = request.builtContext.returnSchema;
+    }
     const maxTokens = budgetToTokenLimit(request);
     if (maxTokens) {
         body.options = { num_predict: maxTokens };
     }
     const response = await postJson(fetchImpl, `${baseUrl}/api/chat`, body, timeoutMs);
-    return parseJsonText(readPath(response, ["message", "content"]));
+    const text = readPath(response, ["message", "content"]);
+    return request.returnShape ? parseJsonText(text) : text;
 }

package/dist/providers/llm/openai.js

@@ -11,15 +11,17 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
             { role: "system", content: request.builtContext.system },
             { role: "user", content: request.builtContext.finalUserMessage },
         ],
-        response_format: {
+    };
+    if (request.builtContext.returnSchema) {
+        body.response_format = {
             type: "json_schema",
             json_schema: {
                 name: "agentscript_generate",
                 strict: true,
                 schema: request.builtContext.returnSchema,
             },
-        },
-    };
+        };
+    }
     const maxTokens = budgetToTokenLimit(request);
     if (maxTokens) {
         body.max_completion_tokens = maxTokens;
@@ -27,5 +29,6 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
     const response = await postJson(fetchImpl, `${baseUrl}/chat/completions`, body, timeoutMs, {
         authorization: `Bearer ${apiKey}`,
     });
-    return parseJsonText(readPath(response, ["choices", 0, "message", "content"]));
+    const text = readPath(response, ["choices", 0, "message", "content"]);
+    return request.returnShape ? parseJsonText(text) : text;
 }

package/dist/providers/mock/index.js

@@ -2,7 +2,7 @@ import { sanitizeForJson } from "../../runtime/json.js";
 import { buildValueFromShape } from "../../runtime/shape.js";
 export class MockLlmProvider {
     async generate(request) {
-        return buildValueFromShape(request.returnShape);
+        return request.returnShape ? buildValueFromShape(request.returnShape) : null;
     }
 }
 export class MockToolProvider {

package/dist/runtime/context.js

@@ -4,7 +4,7 @@ export function buildContext(input) {
     const instruction = sanitizeForJson(input.instruction);
     const instructionText = renderJson(instruction);
     const system = buildSystemPrompt(input.agentName, input.identity);
-    const returnSchema = shapeToSchema(input.returnShape);
+    const returnSchema = input.returnShape ? shapeToSchema(input.returnShape) : undefined;
     return {
         agentName: input.agentName,
         model: input.model,
@@ -76,7 +76,9 @@ function buildFinalUserMessage(context, instructionText, returnSchema) {
         }
     }
     sections.push("Instruction:", instructionText);
-    sections.push("Return JSON matching this schema:", renderJson(returnSchema));
+    if (returnSchema) {
+        sections.push("Return JSON matching this schema:", renderJson(returnSchema));
+    }
     return sections.join("\n");
 }
 function renderJson(value) {
@@ -153,7 +155,7 @@ export function builtContextToJson(context) {
             clippedSize: item.clippedSize,
         })),
         instruction: context.instruction,
-        returnSchema: context.returnSchema,
+        returnSchema: context.returnSchema ?? null,
         budget: budgetToJson(context.budget),
         finalUserMessage: context.finalUserMessage,
     };

package/dist/runtime/generate.js

@@ -58,8 +58,10 @@ export class GenerateRuntime {
                 continue;
             }
             try {
-                const result = coerceValueToShape(rawResult, expr.returnShape);
-                validateValueAgainstShape(result, expr.returnShape, expr.range);
+                const result = expr.returnShape ? coerceValueToShape(rawResult, expr.returnShape) : rawResult;
+                if (expr.returnShape) {
+                    validateValueAgainstShape(result, expr.returnShape, expr.range);
+                }
                 this.trace.push({
                     kind: "generate",
                     data: {

package/dist/runtime/interpreter.js

@@ -151,11 +151,8 @@ class Interpreter {
         this.callDepth += 1;
         const scope = await this.buildFunctionScope(agent, fn, args);
         try {
-            const signal = await this.executeBlock(fn.body, scope);
-            if (!signal) {
-                throw new RuntimeError(`Function '${agent.name}.${name}' completed without return`, fn.range);
-            }
-            return signal.value;
+            const signal = await this.executeBlock(fn.body, scope, true);
+            return signal?.value ?? null;
         }
         finally {
             this.callDepth -= 1;
@@ -194,8 +191,11 @@ class Interpreter {
     findFunction(agent, name) {
         return agent.functions.find((fn) => fn.name === name);
     }
-    async executeBlock(statements, scope) {
-        for (const stmt of statements) {
+    async executeBlock(statements, scope, allowFinalExpressionReturn = false) {
+        for (const [index, stmt] of statements.entries()) {
+            if (allowFinalExpressionReturn && index === statements.length - 1 && stmt.kind === "ExprStmt") {
+                return { kind: "return", value: await this.evaluator.evaluate(stmt.expr, scope) };
+            }
             const result = await this.executeStatement(stmt, scope);
             if (result)
                 return result;

package/dist/semantic/analyzer.js

@@ -366,7 +366,9 @@ class Analyzer {
             this.checkExpression(expr.options.input, scope);
         }
         this.checkGenerateInput(expr);
-        this.checkShapeObject(expr.returnShape);
+        if (expr.returnShape) {
+            this.checkShapeObject(expr.returnShape);
+        }
         this.checkGenerateConfig("model", expr, scope);
         this.checkGenerateConfig("role", expr, scope);
         this.checkGenerateConfig("description", expr, scope);

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` 的语义
@@ -32,15 +32,13 @@ func answer(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({
+    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
-        }
+    generate({ input: "Answer from scratch" }) -> {
+        text string
     }
 }
 ```
@@ -123,15 +119,13 @@ AgentScript 中的作用域不仅是变量可见性规则，也是 prompt contex
 ```agentscript
 func caller(input) {
     use input.goal
-    return helper(input)
+    helper(input)
 }
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) {
-        return {
-            ok boolean
-        }
+    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
 }
 ```
 
@@ -245,10 +235,10 @@ Instruction 是本次 LLM 调用的局部任务，不应混入长期 context。
 
 ### Output contract
 
-Output contract 来自 `return shape`。
+Output contract 来自 `generate` 表达式上可选的 `-> { ... }` shape。
 
 ```agentscript
-return {
+generate({ input: "Answer" }) -> {
     ok boolean
     text string
     error string
@@ -270,13 +260,11 @@ use scratch.summary < 2k
 `generate({ limit: budget }) { ... }` 是 generation budget。
 
 ```agentscript
-return generate({
+generate({
     input: "Summarize"
     limit: 500
-}) {
-    return {
-        text string
-    }
+}) -> {
+    text string
 }
 ```