@rong/agentscript 0.1.1 → 0.1.3

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

@@ -0,0 +1,215 @@
+# 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)
+}
+```
+
+This rule applies to all expression forms, including calls. It does not matter whether the callee resolves to a local function or an agent call. For example, calling another agent by name invokes that agent's `main func`, and the result is returned implicitly:
+
+```agentscript
+agent Planner {
+    main func(input) {
+        generate({ input: "Create a plan" }) -> {
+            steps list[string]
+        }
+    }
+}
+
+agent Controller {
+    func run(input) {
+        Planner(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]
@@ -158,6 +158,8 @@ Shapes are not a full static type system.
 use input.question
 use Requirements < 4k
 use past_lessons < 2k
+use input.question as user
+use docs.summary < 4k as evidence
 ```
 
 ### Rules
@@ -167,17 +169,31 @@ use past_lessons < 2k
 - Memory query results do not automatically enter prompts.
 - Trace events do not automatically enter prompts.
 - `use value < n` applies a context budget.
+- `use value as label` attaches a literal context label to the selected source.
+- `use value < n as label` applies the budget first, then attaches the label.
 - `llm`, `tool`, `agent`, `memory` bindings cannot be used.
 - Function bindings cannot be used.
 - `use` declarations are inherited by child scopes.
 
+### Context labels
+
+The label after `as` is literal label text. It is not an expression, is not evaluated, and does not read variables from scope.
+
+```agentscript
+use docs as evidence
+use docs.summary < 4k as retrieved evidence
+use input.question as user
+```
+
+`as evidence` labels the context section as `evidence` even if a variable named `evidence` exists. Labels organize prompt sections and trace output; they do not change provider message roles such as `system`, `user`, or `assistant`.
+
 ### Deferred evaluation
 
 `use expr < budget` declares a context source, not a snapshot. The expression is re-evaluated when `generate` builds the prompt. This means updates to a variable made after `use` but before `generate` are visible at generation time.
 
 ## 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 +214,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 +382,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 +434,7 @@ main agent Controller {
             result = Executor({ goal: input.goal, step: step })
             results.add(result)
         }
-        return results.summary
+        results.summary
     }
 }
 ```

package/examples/changelog.as

@@ -13,10 +13,10 @@ main agent ChangelogWriter {
             path: input.diff_path
         })
 
-        use input.diff_path
-        use diff < 10k
+        use input.diff_path as diff path
+        use diff < 10k as git diff
 
-        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

@@ -14,10 +14,10 @@ main agent ApiExtractor {
             timeout: 10000
         })
 
-        use input.url
-        use response < 8k
+        use input.url as endpoint
+        use response < 8k as api response
 
-        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

@@ -22,11 +22,11 @@ main agent CodeReviewAssistant {
             max: 100
         })
 
-        use input.path
-        use todos < 4k
-        use fixmes < 4k
+        use input.path as source path
+        use todos < 4k as todo findings
+        use fixmes < 4k as fixme findings
 
-        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

@@ -13,10 +13,10 @@ main agent FileSummarizer {
             path: input.path
         })
 
-        use input.path
-        use content < 8k
+        use input.path as source path
+        use content < 8k as file content
 
-        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

@@ -17,11 +17,11 @@ main agent MarkdownTranslator {
             max: 50
         })
 
-        use input.path
-        use input.target_language
-        use files < 4k
+        use input.path as source path
+        use input.target_language as target language
+        use files < 4k as markdown files
 
-        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.3",
   "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
         }) -> {