@rong/agentscript 0.1.4 → 0.1.5

package/docs/cn/use-as.md

@@ -10,7 +10,7 @@
 
 ```agentscript
 use input.question as user question
-use scratch.summary < 2k as observations
+use scratch.summary max 2k as observations
 ```
 
 含义是：
@@ -25,9 +25,9 @@ use scratch.summary < 2k as observations
 
 ```agentscript
 use expr
-use expr < budget
+use expr max budget
 use expr as label
-use expr < budget as label
+use expr max budget as label
 ```
 
 固定顺序是：
@@ -40,8 +40,8 @@ use expr < budget as label
 
 ```agentscript
 use input.question as user question
-use docs.summary < 4k as retrieved evidence
-use scratch.summary < 2k as observations
+use docs.summary max 4k as retrieved evidence
+use scratch.summary max 2k as observations
 ```
 
 ## Context label
@@ -50,7 +50,7 @@ use scratch.summary < 2k as observations
 
 ```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
 ```
 
@@ -92,7 +92,7 @@ developer
 ```agentscript
 main func(input) {
     scratch = []
-    use scratch.summary < 2k as observations
+    use scratch.summary max 2k as observations
 
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
@@ -150,15 +150,15 @@ use helper
 
 ```agentscript
 results = Search.search(input.question)
-use results < 4k as search results
+use results max 4k as search results
 ```
 
 ## Budget 语义
 
-`use expr < budget` 是 context item budget，限制该 source 渲染进 prompt 的大小。
+`use expr max budget` 是 context item budget，限制该 source 渲染进 prompt 的大小。
 
 ```agentscript
-use docs.summary < 4k as evidence
+use docs.summary max 4k as evidence
 ```
 
 这不同于 `generate({ max_output: ... })` 的 output generation budget。详见 [`generate`](./generate.md)。

package/docs/en/context-engineering.md

@@ -67,7 +67,7 @@ Agent calls create a stronger boundary. A called agent does not see the caller's
 
 ```agentscript
 result = Worker({
-    goal: input.goal
+    goal: input.goal,
     previous: results.summary
 })
 ```

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

@@ -175,10 +175,10 @@ For typical LLM calls, omit `return`:
 
 ```agentscript
 func summarize(content) {
-    use content < 8k
+    use content max 8k
 
     generate({
-        input: "Summarize the content"
+        input: "Summarize the content",
         max_output: 1000
     }) -> {
         title string

package/docs/en/generate.md

@@ -21,12 +21,12 @@ Ordinary code can compute values, call tools, call agents, and organize state. O
 
 ```agentscript
 generate({
-    input: "Classify the issue"
-    max_output: 300
-    attempts: 2
-    temperature: 0.2
-    think: "medium"
-    strict: true
+    input: "Classify the issue",
+    max_output: 300,
+    attempts: 2,
+    temperature: 0.2,
+    think: "medium",
+    strict: true,
     debug: false
 }) -> {
     category string
@@ -40,7 +40,7 @@ The output shape after `->` is optional:
 generate({ input: "Draft a response." })
 ```
 
-When no shape is declared, the runtime should not inject a schema or require structured JSON output.
+When no shape is declared, the runtime should not inject a schema or require structured JSON output. Free-form generate is allowed but not recommended for agent workflows; prefer an explicit output shape so retries, validation, trace, and downstream agent calls stay auditable.
 
 ## Configuration fields
 
@@ -110,7 +110,7 @@ Selected context comes from visible `use` declarations:
 
 ```agentscript
 use input.question as user question
-use scratch.summary < 2k as observations
+use scratch.summary max 2k as observations
 ```
 
 A rendered prompt section may look like:
@@ -162,7 +162,7 @@ The runtime asks the provider for structured output when possible and validates
 
 ```agentscript
 generate({
-    input: "Answer briefly"
+    input: "Answer briefly",
     max_output: 300
 }) -> {
     answer string
@@ -178,10 +178,10 @@ max_output = provider-side generation budget requested by AgentScript
 It is separate from `use` input context budgets:
 
 ```agentscript
-use docs.summary < 4k
+use docs.summary max 4k
 
 generate({
-    input: "Answer from the selected docs"
+    input: "Answer from the selected docs",
     max_output: 800
 }) -> {
     answer string
@@ -191,18 +191,18 @@ generate({
 Difference:
 
 ```text
-use ... < 4k       = input context budget
+use ... max 4k       = input context budget
 max_output: 800    = output generation budget
 ```
 
 ## `attempts`
 
-`attempts` controls how many times the runtime may try to obtain a valid structured result.
+`attempts` controls how many times the runtime may try to obtain a valid structured result. `attempts` is the maximum total number of attempts, including the first one.
 
 ```agentscript
 generate({
-    input: "Extract metadata"
-    max_output: 500
+    input: "Extract metadata",
+    max_output: 500,
     attempts: 3
 }) -> {
     title string
@@ -242,8 +242,8 @@ attempts: 1
 
 ```agentscript
 generate({
-    input: "Brainstorm alternatives"
-    max_output: 1000
+    input: "Brainstorm alternatives",
+    max_output: 1000,
     temperature: 0.7
 }) -> {
     ideas list[string]
@@ -264,11 +264,11 @@ If unsupported, adapter may ignore, warn, or fail according to capability policy
 Recommended values:
 
 ```agentscript
-think: false
-think: true
-think: "auto"
-think: "low"
-think: "medium"
+think: false,
+think: true,
+think: "auto",
+think: "low",
+think: "medium",
 think: "high"
 ```
 
@@ -287,8 +287,8 @@ Example:
 
 ```agentscript
 generate({
-    input: "Analyze the tradeoffs"
-    max_output: 1200
+    input: "Analyze the tradeoffs",
+    max_output: 1200,
     think: "high"
 }) -> {
     decision string
@@ -297,20 +297,16 @@ generate({
 }
 ```
 
-`think` is a provider/model capability hint. Not every model guarantees support.
+`think` is a provider/model capability hint. Not every model guarantees support. If unsupported, the adapter may ignore, warn, or fail according to capability policy.
 
-If unsupported, the runtime may handle it according to policy:
+## Capability policy for provider hints
 
-```text
-ignore
-warn
-fail
-```
+`temperature` and `think` are provider/model capability hints. Unsupported provider hints default to warn in debug mode and ignore otherwise.
 
-Recommended default policy:
+Adapters may ignore, warn, or fail for unsupported hints according to runtime capability policy, but documentation should treat the default as:
 
 ```text
-warn in debug mode, otherwise ignore
+unsupported provider hints default to warn in debug mode and ignore otherwise
 ```
 
 ## `strict`
@@ -319,8 +315,8 @@ warn in debug mode, otherwise ignore
 
 ```agentscript
 generate({
-    input: "Classify the issue"
-    max_output: 300
+    input: "Classify the issue",
+    max_output: 300,
     strict: true
 }) -> {
     category string
@@ -377,8 +373,8 @@ strict is AgentScript runtime control over the output contract.
 
 ```agentscript
 generate({
-    input: "Answer the question"
-    max_output: 800
+    input: "Answer the question",
+    max_output: 800,
     debug: true
 }) -> {
     answer string

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,7 @@ 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).
 
@@ -199,9 +201,9 @@ For the full design semantics, see [`use ... as ...`](./use-as.md).
 
 ```agentscript
 answer = generate({
-    input: "Answer using the selected context."
-    max_output: 800
-    attempts: 3
+    input: "Answer using the selected context.",
+    max_output: 800,
+    attempts: 3,
     debug: true
 }) -> {
     ok boolean
@@ -214,13 +216,13 @@ answer = generate({
 
 - `input` is the per-generation instruction. Required.
 - `max_output` is the output generation budget (number or `2k` style). Optional.
-- `attempts` controls retry for JSON parse errors or shape mismatch. Optional, defaults to 1.
-- `temperature` is a provider sampling hint. Optional.
-- `think` is a provider/model reasoning hint. 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`).
 
@@ -238,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
 }
@@ -269,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)
 }
@@ -289,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
 
@@ -307,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
 })
 ```
@@ -318,9 +320,9 @@ files = Find.run({
 
 ```agentscript
 matches = Grep.run({
-    path: "src"
-    pattern: "TODO"
-    include: "*.ts"
+    path: "src",
+    pattern: "TODO",
+    include: "*.ts",
     max: 100
 })
 ```
@@ -329,8 +331,8 @@ matches = Grep.run({
 
 ```agentscript
 lines = Sed.run({
-    path: "src/main.as"
-    start: 1
+    path: "src/main.as",
+    start: 1,
     max: 20
 })
 ```
@@ -338,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)
 ```
 
@@ -350,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.
@@ -387,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
@@ -402,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
@@ -437,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

@@ -10,7 +10,7 @@ For the larger mental model, see [Context Engineering](./context-engineering.md)
 
 ```agentscript
 use input.question as user question
-use scratch.summary < 2k as observations
+use scratch.summary max 2k as observations
 ```
 
 The meaning is:
@@ -25,9 +25,9 @@ Local variables not selected with `use` do not enter the prompt.
 
 ```agentscript
 use expr
-use expr < budget
+use expr max budget
 use expr as label
-use expr < budget as label
+use expr max budget as label
 ```
 
 The fixed order is:
@@ -40,8 +40,8 @@ Examples:
 
 ```agentscript
 use input.question as user question
-use docs.summary < 4k as retrieved evidence
-use scratch.summary < 2k as observations
+use docs.summary max 4k as retrieved evidence
+use scratch.summary max 2k as observations
 ```
 
 ## Context labels
@@ -50,7 +50,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
 ```
 
@@ -92,7 +92,7 @@ developer
 ```agentscript
 main func(input) {
     scratch = []
-    use scratch.summary < 2k as observations
+    use scratch.summary max 2k as observations
 
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
@@ -150,15 +150,15 @@ Use the data returned by these capabilities instead:
 
 ```agentscript
 results = Search.search(input.question)
-use results < 4k as search results
+use results max 4k as search results
 ```
 
 ## Budget semantics
 
-`use expr < budget` is a context item budget. It limits how much of that source may be rendered into the prompt.
+`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 < 4k as evidence
+use docs.summary max 4k as evidence
 ```
 
 This is different from `generate({ max_output: ... })`, which is an output generation budget. See [`generate`](./generate.md).

package/examples/changelog.as

@@ -14,7 +14,7 @@ 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", max_output: 1200 }) -> {
             title string

package/examples/extract.as

@@ -15,7 +15,7 @@ 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", max_output: 1200 }) -> {
             records list[json]

package/examples/review.as

@@ -23,8 +23,8 @@ 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", max_output: 1200 }) -> {
             summary string

package/examples/summarize.as

@@ -14,7 +14,7 @@ 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", max_output: 1000 }) -> {
             title string

package/examples/translate.as

@@ -19,7 +19,7 @@ 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", max_output: 1000 }) -> {
             target_language string

package/package.json

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

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
         })
     }