@rong/agentscript 0.1.3 → 0.1.5

package/docs/en/language.md

@@ -150,16 +150,18 @@ Supported shape types: `string`, `number`, `boolean`, `json`, `list`, `list[T]`
 
 Shapes are not a full static type system.
 
+Object literals use JSON-like syntax: fields are written as `key: value`, and multiple fields must be separated with commas.
+
 ## Explicit context with `use`
 
 `use` selects values that may be included in later `generate` prompts within the current scope and child scopes.
 
 ```agentscript
 use input.question
-use Requirements < 4k
-use past_lessons < 2k
+use Requirements max 4k
+use past_lessons max 2k
 use input.question as user
-use docs.summary < 4k as evidence
+use docs.summary max 4k as evidence
 ```
 
 ### Rules
@@ -168,9 +170,9 @@ use docs.summary < 4k as evidence
 - Tool outputs do not automatically enter prompts.
 - Memory query results do not automatically enter prompts.
 - Trace events do not automatically enter prompts.
-- `use value < n` applies a context budget.
+- `use value max 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.
+- `use value max 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.
@@ -181,7 +183,7 @@ The label after `as` is literal label text. It is not an expression, is not eval
 
 ```agentscript
 use docs as evidence
-use docs.summary < 4k as retrieved evidence
+use docs.summary max 4k as retrieved evidence
 use input.question as user
 ```
 
@@ -189,7 +191,9 @@ use input.question as user
 
 ### 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.
+`use expr max 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.
+
+For the full design semantics, see [`use ... as ...`](./use-as.md).
 
 ## Generate
 
@@ -197,9 +201,9 @@ use input.question as user
 
 ```agentscript
 answer = generate({
-    input: "Answer using the selected context."
-    limit: 800
-    attempts: 3
+    input: "Answer using the selected context.",
+    max_output: 800,
+    attempts: 3,
     debug: true
 }) -> {
     ok boolean
@@ -211,14 +215,19 @@ answer = generate({
 ### Semantics
 
 - `input` is the per-generation instruction. Required.
-- `limit` is the generation budget (number or `2k` style). Optional.
-- `attempts` controls retry for JSON parse errors or shape mismatch. Optional, defaults to 1.
+- `max_output` is the output generation budget (number or `2k` style). Optional.
+- `attempts` controls retry for JSON parse errors or shape mismatch. It is the maximum total number of attempts, including the first one. Optional, defaults to 1.
+- `temperature` is a provider sampling hint. Optional. Unsupported provider hints default to warn in debug mode and ignore otherwise.
+- `think` is a provider/model reasoning hint. Optional. Unsupported provider hints default to warn in debug mode and ignore otherwise.
+- `strict` controls shape validation strictness. Optional, defaults to false.
 - `debug` prints the full prompt to stderr. Optional, defaults to false.
 - 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.
+- 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. Free-form generate is allowed but not recommended for agent workflows.
 - Provider errors (auth, network, timeout, missing model) fail directly without retry.
 - Shape validation includes coercion (e.g. `"true"` -> `true`, `"42"` -> `42`).
 
+For prompt construction, identity, retry, and trace semantics, see [`generate`](./generate.md).
+
 ## Control flow
 
 ### If / else
@@ -231,14 +240,14 @@ if answer.ok and not input.dry_run {
 }
 ```
 
-Supported operators: `==`, `!=`, `and`, `or`, `not`. `<` is not a general comparison operator — it is used for budgets and loop limits.
+Supported operators: `==`, `!=`, `<`, `and`, `or`, `not`. Context budgets and loop limits use `max`, so `<` remains an ordinary comparison operator like `==`.
 
 ### Loop until
 
 ```agentscript
 done = false
 
-loop until done < 6 {
+loop until done max 6 {
     observation = observe(input)
     done = observation.ok
 }
@@ -262,7 +271,7 @@ Each iteration creates a child scope. Outer variables updated inside the loop pe
 ### For in
 
 ```agentscript
-for step in plan.steps < 12 {
+for step in plan.steps max 12 {
     result = Executor(step)
     results.add(result)
 }
@@ -282,7 +291,7 @@ summary = items.summary
 - `list[index]` is read-only. Index must be a non-negative integer.
 - `list.add(value)` mutates the list. Takes exactly one argument.
 - `.length` returns the list length.
-- `.summary` returns a JSON-safe runtime view of the list. It is not an LLM-generated summary or semantic compression; any prompt-size reduction comes from explicit context budgets such as `use scratch.summary < 2k`.
+- `.summary` returns a JSON-safe runtime view of the list. It is not an LLM-generated summary or semantic compression; any prompt-size reduction comes from explicit context budgets such as `use scratch.summary max 2k`.
 
 ## Tools
 
@@ -300,9 +309,9 @@ import tool Http from "https://api.example.com"
 
 ```agentscript
 files = Find.run({
-    path: "."
-    name: "*.ts"
-    type: "file"
+    path: ".",
+    name: "*.ts",
+    type: "file",
     max: 50
 })
 ```
@@ -311,9 +320,9 @@ files = Find.run({
 
 ```agentscript
 matches = Grep.run({
-    path: "src"
-    pattern: "TODO"
-    include: "*.ts"
+    path: "src",
+    pattern: "TODO",
+    include: "*.ts",
     max: 100
 })
 ```
@@ -322,8 +331,8 @@ matches = Grep.run({
 
 ```agentscript
 lines = Sed.run({
-    path: "src/main.as"
-    start: 1
+    path: "src/main.as",
+    start: 1,
     max: 20
 })
 ```
@@ -331,10 +340,21 @@ lines = Sed.run({
 ### File
 
 ```agentscript
-content = File.read({ path: "README.md" })
-entries = File.list({ path: "src" })
-result = File.write({ path: "output.md", content: "# Result" })
-result = File.patch({ path: "file.as", search: "old", replace: "new" })
+content = File.read({
+    path: "README.md"
+})
+entries = File.list({
+    path: "src"
+})
+result = File.write({
+    path: "output.md",
+    content: "# Result"
+})
+result = File.patch({
+    path: "file.as",
+    search: "old",
+    replace: "new"
+})
 result = File.undo(effects)
 ```
 
@@ -343,14 +363,24 @@ Write and patch operations return undoable effect records. `File.undo` accepts a
 ### Env
 
 ```agentscript
-home = Env.get({ name: "HOME" })
+home = Env.get({
+    name: "HOME"
+})
 ```
 
 ### Http
 
 ```agentscript
-response = Http.get({ url: "/api/data", headers: { Authorization: "Bearer ..." }, timeout: 10000 })
-response = Http.post({ url: "/api/submit", body: { key: "value" }, timeout: 10000 })
+response = Http.get({
+    url: "/api/data",
+    headers: { Authorization: "Bearer ..." },
+    timeout: 10000
+})
+response = Http.post({
+    url: "/api/submit",
+    body: { key: "value" },
+    timeout: 10000
+})
 ```
 
 HTTP requests are restricted to the origin of the import URI.
@@ -380,7 +410,7 @@ import file Requirements from "./requirements.md"
 import file Config from "./config.json"
 
 func answer(input) {
-    use Requirements < 4k
+    use Requirements max 4k
     use Config
     generate({ input: "Answer from the referenced file." }) -> {
         ok boolean
@@ -395,18 +425,18 @@ Text files are loaded as strings. JSON files are parsed as JSON values. File con
 
 ```agentscript
 Lessons.add({
-    kind: "lesson"
-    text: reflection.insight
+    kind: "lesson",
+    text: reflection.insight,
     goal: input.goal
 })
 
 past = Lessons.query({
-    kind: "lesson"
-    text: input.goal
+    kind: "lesson",
+    text: input.goal,
     limit: 5
 })
 
-use past < 2k
+use past max 2k
 ```
 
 ### Rules
@@ -430,8 +460,11 @@ main agent Controller {
     main func(input) {
         plan = Planner(input)
         results = []
-        for step in plan.steps < 10 {
-            result = Executor({ goal: input.goal, step: step })
+        for step in plan.steps max 10 {
+            result = Executor({
+                goal: input.goal,
+                step: step
+            })
             results.add(result)
         }
         results.summary

package/docs/en/use-as.md

@@ -0,0 +1,225 @@
+# `use ... as ...`
+
+This document defines how `use` selects prompt context in AgentScript, including context labels, budgets, scope visibility, deferred evaluation, and trace requirements.
+
+For the larger mental model, see [Context Engineering](./context-engineering.md). For prompt construction and output contracts, see [`generate`](./generate.md).
+
+## Purpose
+
+`use` is not a variable read, assignment, or namespace import. It declares a prompt context source.
+
+```agentscript
+use input.question as user question
+use scratch.summary max 2k as observations
+```
+
+The meaning is:
+
+```text
+make this source visible to later generate calls in the current scope and child scopes
+```
+
+Local variables not selected with `use` do not enter the prompt.
+
+## Syntax
+
+```agentscript
+use expr
+use expr max budget
+use expr as label
+use expr max budget as label
+```
+
+The fixed order is:
+
+```text
+what to select -> how much to include -> what role it plays as context
+```
+
+Examples:
+
+```agentscript
+use input.question as user question
+use docs.summary max 4k as retrieved evidence
+use scratch.summary max 2k as observations
+```
+
+## 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 max 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 affect:
+
+- prompt section labels
+- trace display
+- context organization
+- debug and audit readability
+
+Labels do not affect:
+
+- agent identity
+- provider message roles
+- tool permissions
+- system/user/assistant authority
+
+## Provider roles are not context labels
+
+Provider roles such as `system`, `user`, `assistant`, and `tool` are LLM API transport details. AgentScript context labels are prompt-internal organization labels.
+
+The following labels are reserved to avoid confusion with provider roles:
+
+```text
+system
+assistant
+tool
+developer
+```
+
+`user` is allowed as a context label because it often means "this context item is user input". It still does not create a separate provider `user` message.
+
+## Deferred evaluation
+
+`use expr` declares a source, not a snapshot. The expression is evaluated when a visible `generate` builds its prompt.
+
+```agentscript
+main func(input) {
+    scratch = []
+    use scratch.summary max 2k as observations
+
+    scratch.add({ fact: "A" })
+    scratch.add({ fact: "B" })
+
+    generate({ input: "Answer from observations" }) -> {
+        text string
+    }
+}
+```
+
+The `generate` call sees both facts.
+
+This keeps `use` as a context contract instead of a value copy.
+
+## Scope visibility
+
+A `use` declaration is visible to later `generate` calls in the same scope and child scopes.
+
+```agentscript
+use input.question as user question
+
+if input.needs_detail {
+    use input.detail as detail
+    generate({ input: "Answer with detail" }) -> {
+        text string
+    }
+}
+```
+
+The inner `generate` can see both `user question` and `detail`. The `detail` context does not leak outside the block.
+
+Function and agent calls form independent context boundaries. A callee does not automatically inherit the caller's selected context.
+
+## What cannot be used
+
+Runtime capabilities must not enter prompt context:
+
+- imported tools
+- imported LLM/model bindings
+- imported agent bindings
+- memory handles
+- function bindings
+- provider URIs and workspace/runtime configuration
+
+Invalid examples:
+
+```agentscript
+use Search
+use Qwen
+use Worker
+use helper
+```
+
+Use the data returned by these capabilities instead:
+
+```agentscript
+results = Search.search(input.question)
+use results max 4k as search results
+```
+
+## Budget semantics
+
+`use expr max budget` is a context item budget. It limits how much of that source may be rendered into the prompt.
+
+```agentscript
+use docs.summary max 4k as evidence
+```
+
+This is different from `generate({ max_output: ... })`, which is an output generation budget. See [`generate`](./generate.md).
+
+## Prompt rendering
+
+A labeled context item is rendered as a context section:
+
+```text
+Context:
+[user question]
+source: input.question
+What is AgentScript?
+
+[observations]
+source: scratch.summary
+[
+  { "fact": "..." }
+]
+```
+
+If no label is provided, the renderer may use the numeric context index and include the source expression separately.
+
+## Trace requirements
+
+A `use` trace event records the declaration:
+
+```json
+{
+  "kind": "use",
+  "data": {
+    "source": "scratch.summary",
+    "label": "observations",
+    "budget": { "amount": 2, "unit": "k" }
+  }
+}
+```
+
+A generated built context item records the resolved value and rendering metadata:
+
+```json
+{
+  "index": 0,
+  "source": "scratch.summary",
+  "label": "observations",
+  "value": [{ "fact": "A" }],
+  "text": "[...]",
+  "budget": { "amount": 2, "unit": "k" },
+  "clipped": false
+}
+```
+
+Trace must make the selected source, label, budget, clipping status, and resolved value auditable.
+
+## Design checklist
+
+Before changing `use`, verify:
+
+- Does unused data stay out of prompts?
+- Is the source evaluated at `generate` time?
+- Does the label remain literal text rather than an expression?
+- Are provider roles still separate from context labels?
+- Are budgets attached to context items, not the whole generation?
+- Do function and agent boundaries prevent context leakage?

package/examples/changelog.as

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

package/examples/extract.as

@@ -15,9 +15,9 @@ main agent ApiExtractor {
         })
 
         use input.url as endpoint
-        use response < 8k as api response
+        use response max 8k as api response
 
-        generate({ input: "Extract normalized data from the API response", limit: 1200 }) -> {
+        generate({ input: "Extract normalized data from the API response", max_output: 1200 }) -> {
             records list[json]
             fields list[string]
             warnings list[string]

package/examples/review.as

@@ -23,10 +23,10 @@ main agent CodeReviewAssistant {
         })
 
         use input.path as source path
-        use todos < 4k as todo findings
-        use fixmes < 4k as fixme findings
+        use todos max 4k as todo findings
+        use fixmes max 4k as fixme findings
 
-        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", max_output: 1200 }) -> {
             summary string
             findings list[string]
             suggested_fixes list[string]

package/examples/summarize.as

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

package/examples/translate.as

@@ -19,9 +19,9 @@ main agent MarkdownTranslator {
 
         use input.path as source path
         use input.target_language as target language
-        use files < 4k as markdown files
+        use files max 4k as markdown files
 
-        generate({ input: "Create a practical markdown translation plan", limit: 1000 }) -> {
+        generate({ input: "Create a practical markdown translation plan", max_output: 1000 }) -> {
             target_language string
             files list[string]
             glossary_notes list[string]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rong/agentscript",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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
 
-        generate({ input: "Reply to the CLI user by name", limit: 300 }) -> {
+        generate({ input: "Reply to the CLI user by name", max_output: 300 }) -> {
             ok boolean
             message string
         }

package/tutorials/memory.as

@@ -5,14 +5,14 @@ main agent MemoryDemo {
         topic string
     }) {
         Notes.add({
-            kind: "note"
-            text: input.topic
+            kind: "note",
+            text: input.topic,
             topic: input.topic
         })
 
         Notes.query({
-            kind: "note"
-            text: input.topic
+            kind: "note",
+            text: input.topic,
             limit: 3
         })
     }

package/tutorials/plan-execute.as

@@ -31,7 +31,7 @@ main agent PlanAndExecute {
             }
         ]
 
-        for step in steps < 6 {
+        for step in steps max 6 {
             outcome = run_step(input.goal, step, results)
             results.add(outcome.result)
 
@@ -73,9 +73,9 @@ main agent PlanAndExecute {
 
     func finish(goal, results) {
         use goal
-        use results.summary < 2k
+        use results.summary max 2k
 
-        generate({ input: "Create the final answer from executed steps", limit: 800 }) -> {
+        generate({ input: "Create the final answer from executed steps", max_output: 800 }) -> {
             ok boolean
             text string
             error string
@@ -91,9 +91,9 @@ agent Planner {
     main func(input) {
         use input.goal
         use input.problem
-        use input.previous < 1k
+        use input.previous max 1k
 
-        generate({ input: "Create a three step plan", limit: 600 }) -> {
+        generate({ input: "Create a three step plan", max_output: 600 }) -> {
             step1 string
             step2 string
             step3 string
@@ -109,7 +109,7 @@ agent Executor {
     main func(input) {
         use input.goal
         use input.step
-        use input.previous < 1k
+        use input.previous max 1k
 
         query = Search.query(input.goal, input.step, input.previous)
         raw = Search.search(query)
@@ -121,7 +121,7 @@ agent Executor {
 
         use observation
 
-        generate({ input: "Report the result of this step", limit: 500 }) -> {
+        generate({ input: "Report the result of this step", max_output: 500 }) -> {
             ok boolean
             output json
             error string
@@ -139,7 +139,7 @@ agent Verifier {
         use input.step
         use input.result
 
-        generate({ input: "Verify this step result", limit: 300 }) -> {
+        generate({ input: "Verify this step result", max_output: 300 }) -> {
             ok boolean
             reason string
         }