@rong/agentscript 0.1.1 → 0.1.2

package/README.md

@@ -2,12 +2,12 @@
 
 > **Agent context as code.**
 > `use` declares what the model can see.
-> `generate` defines the only LLM call site and its return shape.
+> `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" }) -> {
+generate({ input: "Answer from observations" }) -> {
     ok boolean
     text string
 }
@@ -64,7 +64,7 @@ main agent FileSummarizer {
         use input.path
         use content < 8k
 
-        return generate({
+        generate({
             input: "Summarize the file for a busy teammate"
             limit: 1000
         }) -> {
@@ -93,7 +93,7 @@ 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.
+The optional block after `generate` is an output schema, not ordinary object construction.
 
 ## What problem it solves
 
@@ -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 *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.
+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
 
@@ -161,7 +161,7 @@ AgentScript doesn't hardcode agent patterns as keywords. You compose them from t
 | **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.
+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
 
@@ -191,13 +191,13 @@ 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" }) -> {
+        generate({ input: "Answer using only the observations" }) -> {
             ok boolean
             text string
             error string
@@ -209,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,8 +408,7 @@ class Parser {
         this.consume("(");
         const options = this.parseGenerateOptions();
         this.consume(")");
-        this.consume("->");
-        const returnShape = this.parseShapeObject();
+        const returnShape = this.match("->") ? this.parseShapeObject() : undefined;
         return {
             kind: "GenerateExpr",
             options,

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

@@ -32,7 +32,7 @@ func answer(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({
+    generate({
         input: "Answer the question using collected facts"
         limit: 800
     }) -> {
@@ -61,7 +61,7 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) -> {
+    generate({ input: "Answer from scratch" }) -> {
         text string
     }
 }
@@ -119,12 +119,12 @@ 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" }) -> {
+    generate({ input: "Work on detail" }) -> {
         ok boolean
     }
 }
@@ -235,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
@@ -260,7 +260,7 @@ use scratch.summary < 2k
 `generate({ limit: budget }) { ... }` 是 generation budget。
 
 ```agentscript
-return generate({
+generate({
     input: "Summarize"
     limit: 500
 }) -> {

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

@@ -0,0 +1,197 @@
+# AgentScript 隐式返回规范草案
+
+本文档描述 AgentScript 函数的隐式返回规则草案。
+
+## 1. 基本规则
+
+函数体最后一个顶层表达式可以作为函数返回值。
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+等价于：
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    return generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+这个规则称为：
+
+```text
+final expression return
+```
+
+## 2. 可隐式返回的表达式
+
+允许最后一行隐式返回以下表达式形式：
+
+```text
+generate(...) -> shape
+普通函数调用
+agent 调用
+变量引用
+字段访问
+索引访问
+object literal
+list literal
+```
+
+例如：
+
+```agentscript
+func run(input) {
+    Worker(input)
+}
+```
+
+```agentscript
+func get_result(result) {
+    result.value
+}
+```
+
+```agentscript
+func observe(action) {
+    {
+        facts: [action.summary],
+        source: action.source
+    }
+}
+```
+
+## 3. 不可隐式返回的语句
+
+下面这些不是表达式，不参与隐式返回：
+
+```text
+use 声明
+赋值语句
+import
+loop
+repeat
+for
+if/else，早期版本可先不表达式化
+```
+
+例如：
+
+```agentscript
+func bad(input) {
+    use input.question
+}
+```
+
+这里没有返回表达式，函数返回 `none`，或由 semantic analyzer 给出 warning。
+
+赋值也不返回：
+
+```agentscript
+func f() {
+    x = answer()
+}
+```
+
+如果要返回，需要写：
+
+```agentscript
+func f() {
+    x = answer()
+    x
+}
+```
+
+## 4. 显式 `return` 优先
+
+显式 `return` 仍然合法，并且在复杂控制流中推荐使用。
+
+```agentscript
+func answer(input) {
+    if input.dry_run {
+        return {
+            ok: false,
+            answer: "dry run"
+        }
+    }
+
+    generate({ input: "Answer" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## 5. 无返回值
+
+如果函数没有显式 `return`，最后一行也不是可返回表达式，则返回：
+
+```agentscript
+none
+```
+
+可以显式写：
+
+```agentscript
+return none
+```
+
+用于表达“此函数只产生副作用”。
+
+## 6. 推荐风格
+
+对于典型 LLM 调用，推荐省略 `return`：
+
+```agentscript
+func summarize(content) {
+    use content < 8k
+
+    generate({
+        input: "Summarize the content"
+        limit: 1000
+    }) -> {
+        title string
+        summary string
+        key_points list[string]
+    }
+}
+```
+
+对于分支、提前退出、错误处理，推荐使用显式 `return`：
+
+```agentscript
+func answer(input) {
+    if not input.question {
+        return {
+            ok: false,
+            answer: ""
+        }
+    }
+
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## 一句话定义
+
+```text
+A function returns the value of its final top-level expression when no explicit return is reached.
+```

package/docs/cn/language.md

@@ -27,7 +27,7 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) -> {
+        generate({ input: "Answer the question" }) -> {
             ok boolean
             answer string
         }
@@ -138,7 +138,7 @@ func careful(input) {
 Shape 用于输入校验和 `generate` 输出校验：
 
 ```agentscript
-return generate({ input: "Extract facts" }) -> {
+generate({ input: "Extract facts" }) -> {
     ok boolean
     title string
     items list[json]
@@ -177,7 +177,7 @@ use past_lessons < 2k
 
 ## Generate
 
-`generate` 调用当前模型，需要 `input` 指令和返回 shape。
+`generate` 调用当前模型，需要 `input` 指令。返回 shape 是可选的。
 
 ```agentscript
 answer = generate({
@@ -198,7 +198,8 @@ answer = generate({
 - `limit`：生成预算（数字或 `2k` 格式）。可选。
 - `attempts`：JSON 解析失败或 shape 不匹配时的重试次数。可选，默认 1。
 - `debug`：将完整 prompt 打印到 stderr。可选，默认 false。
-- `-> { ... }` 块声明期望的输出 shape。
+- 可选的 `-> { ... }` 块声明期望的输出 shape。
+- 不写 `-> { ... }` 时，`generate` 输出无约束：AgentScript 不会在 prompt 中加入返回 schema，不会要求 provider 使用结构化输出，也不会对返回值做类型强制转换或 shape 校验。
 - Provider 错误（认证、网络、超时、模型不存在）直接失败，不做重试。
 - Shape 校验包含类型强制转换（如 `"true"` -> `true`，`"42"` -> `42`）。
 
@@ -365,7 +366,7 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) -> {
+    generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
         answer string
     }
@@ -417,7 +418,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```

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

@@ -50,13 +50,13 @@ main agent ResearchAgent {
         question string
     }) {
         use input.question
-        return answer(input.question)
+        answer(input.question)
     }
 
     func answer(question) {
         use question
 
-        return generate({ input: "Answer the question" }) -> {
+        generate({ input: "Answer the question" }) -> {
             ok boolean
             text string
         }
@@ -103,7 +103,7 @@ agent A {
         model Strong
         description "Use a stronger model for this function."
 
-        return generate({ input: "Answer carefully" }) -> {
+        generate({ input: "Answer carefully" }) -> {
             text string
         }
     }
@@ -130,7 +130,7 @@ V0 运行时数据以 JSON 为核心：
 `generate` 返回 shape 使用轻量标注：
 
 ```agentscript
-return generate({ input: "Extract facts" }) -> {
+generate({ input: "Extract facts" }) -> {
     facts list[string]
     source string
     meta json
@@ -149,7 +149,7 @@ func compose(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({ input: "Answer using only the context" }) -> {
+    generate({ input: "Answer using only the context" }) -> {
         ok boolean
         text string
     }

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

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

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

@@ -210,7 +210,7 @@ agent Reflector {
     main func(input) {
         use input
 
-        return generate({
+        generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
         }) -> {
@@ -286,13 +286,13 @@ main agent Learner {
             ok: result.ok
         })
 
-        return result
+        result
     }
 
     func reflect(run) {
         use run
 
-        return generate({
+        generate({
             input: "Extract one reusable lesson from this run.",
             attempts: 3
         }) -> {

package/docs/en/context-engineering.md

@@ -30,7 +30,7 @@ func answer(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({
+    generate({
         input: "Answer the question using collected facts"
         limit: 800
     }) -> {
@@ -55,7 +55,7 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) -> {
+    generate({ input: "Answer from scratch" }) -> {
         text string
     }
 }
@@ -99,12 +99,12 @@ Each function call creates an independent context boundary.
 ```agentscript
 func caller(input) {
     use input.goal
-    return helper(input)
+    helper(input)
 }
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) -> {
+    generate({ input: "Work on detail" }) -> {
         ok boolean
     }
 }
@@ -207,10 +207,10 @@ The instruction is the per-call task. `limit`, `attempts`, and `debug` are local
 
 ### Output contract
 
-Comes from `return { ... }` shape.
+Comes from the optional `-> { ... }` shape on a `generate` expression.
 
 ```agentscript
-return {
+generate({ input: "Answer" }) -> {
     ok boolean
     text string
     error string

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

@@ -0,0 +1,197 @@
+# AgentScript Final Expression Return
+
+This document describes the implicit return rule for AgentScript functions.
+
+## 1. Basic rule
+
+The final top-level expression in a function body can be used as the function return value.
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+This is equivalent to:
+
+```agentscript
+func answer(input) {
+    use input.question
+
+    return generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+This rule is called:
+
+```text
+final expression return
+```
+
+## 2. Expressions that can be implicitly returned
+
+The final line can implicitly return these expression forms:
+
+```text
+generate(...) -> shape
+regular function call
+agent call
+variable reference
+field access
+index access
+object literal
+list literal
+```
+
+Examples:
+
+```agentscript
+func run(input) {
+    Worker(input)
+}
+```
+
+```agentscript
+func get_result(result) {
+    result.value
+}
+```
+
+```agentscript
+func observe(action) {
+    {
+        facts: [action.summary],
+        source: action.source
+    }
+}
+```
+
+## 3. Statements that cannot be implicitly returned
+
+The following constructs are not expressions and do not participate in final expression return:
+
+```text
+use declaration
+assignment statement
+import
+loop
+repeat
+for
+if/else, which can remain non-expression syntax in early versions
+```
+
+Example:
+
+```agentscript
+func bad(input) {
+    use input.question
+}
+```
+
+This function has no return expression. It returns `none`, or the semantic analyzer may report a warning.
+
+Assignment also does not return a value:
+
+```agentscript
+func f() {
+    x = answer()
+}
+```
+
+To return the assigned value, write:
+
+```agentscript
+func f() {
+    x = answer()
+    x
+}
+```
+
+## 4. Explicit `return` takes priority
+
+Explicit `return` remains valid and is recommended for complex control flow.
+
+```agentscript
+func answer(input) {
+    if input.dry_run {
+        return {
+            ok: false,
+            answer: "dry run"
+        }
+    }
+
+    generate({ input: "Answer" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## 5. No return value
+
+If a function has no explicit `return` and its final line is not a returnable expression, it returns:
+
+```agentscript
+none
+```
+
+This can also be written explicitly:
+
+```agentscript
+return none
+```
+
+Use this form to express that a function only produces side effects.
+
+## 6. Recommended style
+
+For typical LLM calls, omit `return`:
+
+```agentscript
+func summarize(content) {
+    use content < 8k
+
+    generate({
+        input: "Summarize the content"
+        limit: 1000
+    }) -> {
+        title string
+        summary string
+        key_points list[string]
+    }
+}
+```
+
+For branches, early exits, and error handling, use explicit `return`:
+
+```agentscript
+func answer(input) {
+    if not input.question {
+        return {
+            ok: false,
+            answer: ""
+        }
+    }
+
+    use input.question
+
+    generate({ input: "Answer the question" }) -> {
+        ok boolean
+        answer string
+    }
+}
+```
+
+## One-sentence definition
+
+```text
+A function returns the value of its final top-level expression when no explicit return is reached.
+```

package/docs/en/language.md

@@ -27,7 +27,7 @@ main agent Assistant {
         question string
     }) {
         use input.question
-        return generate({ input: "Answer the question" }) -> {
+        generate({ input: "Answer the question" }) -> {
             ok boolean
             answer string
         }
@@ -138,7 +138,7 @@ Runtime values are JSON-oriented:
 Shapes are used for input validation and `generate` output validation:
 
 ```agentscript
-return generate({ input: "Extract facts" }) -> {
+generate({ input: "Extract facts" }) -> {
     ok boolean
     title string
     items list[json]
@@ -177,7 +177,7 @@ use past_lessons < 2k
 
 ## Generate
 
-`generate` calls the current model and requires an `input` instruction plus a return shape.
+`generate` calls the current model and requires an `input` instruction. A return shape is optional.
 
 ```agentscript
 answer = generate({
@@ -198,7 +198,8 @@ 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 `-> { ... }` block declares the expected output shape.
+- The optional `-> { ... }` block declares the expected output shape.
+- Without `-> { ... }`, the generate output is unconstrained: AgentScript does not add a return schema to the prompt, does not request provider structured output, and does not coerce or validate the returned value.
 - Provider errors (auth, network, timeout, missing model) fail directly without retry.
 - Shape validation includes coercion (e.g. `"true"` -> `true`, `"42"` -> `42`).
 
@@ -365,7 +366,7 @@ import file Config from "./config.json"
 func answer(input) {
     use Requirements < 4k
     use Config
-    return generate({ input: "Answer from the referenced file." }) -> {
+    generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
         answer string
     }
@@ -417,7 +418,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```

package/examples/changelog.as

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

package/examples/extract.as

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

package/examples/review.as

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

package/examples/summarize.as

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

package/examples/translate.as

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

package/package.json

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

package/tutorials/cli.as

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

package/tutorials/helloworld.as

@@ -6,7 +6,7 @@ main agent {
     description "Return a simple hello world response."
 
     main func(input {}) {
-        return {
+        {
             ok: true,
             message: "Hello, AgentScript!"
         }

package/tutorials/memory.as

@@ -10,7 +10,7 @@ main agent MemoryDemo {
             topic: input.topic
         })
 
-        return Notes.query({
+        Notes.query({
             kind: "note"
             text: input.topic
             limit: 3

package/tutorials/plan-execute.as

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

package/tutorials/react.as

@@ -25,14 +25,14 @@ main agent ResearchAgent {
             done = enough(input.question, scratch)
         }
 
-        return answer(input.question, scratch)
+        answer(input.question, scratch)
     }
 
     func reason(question, scratch) {
         use question
         use scratch.summary < 1k
 
-        return generate({ input: "Choose the next search focus", limit: 300 }) -> {
+        generate({ input: "Choose the next search focus", limit: 300 }) -> {
             focus string
             why string
         }
@@ -42,7 +42,7 @@ main agent ResearchAgent {
         raw_query = Search.query(question, thought)
         raw_result = Search.search(raw_query)
 
-        return {
+        {
             query: raw_query.summary,
             result: {
                 summary: raw_result.summary,
@@ -60,7 +60,7 @@ main agent ResearchAgent {
 
         use raw
 
-        return generate({ input: "Summarize the useful observation", limit: 400 }) -> {
+        generate({ input: "Summarize the useful observation", limit: 400 }) -> {
             facts list[string]
             source string
         }
@@ -74,14 +74,14 @@ main agent ResearchAgent {
             done boolean
         }
 
-        return verdict.done
+        verdict.done
     }
 
     func answer(question, scratch) {
         use question
         use scratch.summary < 2k
 
-        return generate({ input: "Answer using only the observations", limit: 800 }) -> {
+        generate({ input: "Answer using only the observations", limit: 800 }) -> {
             ok boolean
             text string
             error string

package/tutorials/repl.as

@@ -22,7 +22,7 @@ main agent ReplGuide {
             }
         ]
 
-        return {
+        {
             ok: true,
             title: "AgentScript REPL quick start",
             commands: commands

package/tutorials/self-improve.as

@@ -40,13 +40,13 @@ main agent SelfImprover {
             ok: result.ok
         })
 
-        return result
+        result
     }
 
     func reflect(run) {
         use run
 
-        return generate({
+        generate({
             input: "Extract one durable lesson that could improve a future run.",
             attempts: 3
         }) -> {