@rong/agentscript 0.1.0 → 0.1.2

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

@@ -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
-            }
+        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
-    }
+generate({ input: "Extract facts" }) -> {
+    ok boolean
+    title string
+    items list[json]
+    meta json
 }
 ```
 
@@ -181,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({
@@ -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,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 `return { ... }` 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`).
 
@@ -371,11 +366,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
-        }
+    generate({ input: "Answer from the referenced file." }) -> {
+        ok boolean
+        answer string
     }
 }
 ```
@@ -425,7 +418,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```
@@ -466,7 +459,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
-            }
+        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
-            }
+        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]
-            }
+        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]
-            }
+        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
-            }
+        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.2",
   "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
-            }
+        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,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
-            }
+        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
-            }
+        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
-            }
+        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
-            }
+        generate({ input: "Verify this step result", limit: 300 }) -> {
+            ok boolean
+            reason string
         }
     }
 }

package/tutorials/react.as

@@ -25,18 +25,16 @@ 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 }) {
-            return {
-                focus string
-                why string
-            }
+        generate({ input: "Choose the next search focus", limit: 300 }) -> {
+            focus string
+            why string
         }
     }
 
@@ -44,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,
@@ -62,11 +60,9 @@ main agent ResearchAgent {
 
         use raw
 
-        return generate({ input: "Summarize the useful observation", limit: 400 }) {
-            return {
-                facts list[string]
-                source string
-            }
+        generate({ input: "Summarize the useful observation", limit: 400 }) -> {
+            facts list[string]
+            source string
         }
     }
 
@@ -74,25 +70,21 @@ 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
+        verdict.done
     }
 
     func answer(question, scratch) {
         use question
         use scratch.summary < 2k
 
-        return generate({ input: "Answer using only the observations", limit: 800 }) {
-            return {
-                ok boolean
-                text string
-                error string
-            }
+        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

@@ -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({
@@ -42,19 +40,17 @@ 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
-        }) {
-            return {
-                insight string
-            }
+        }) -> {
+            insight string
         }
     }
 }