@rong/agentscript 0.1.2 → 0.1.4

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 < 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 < budget
+use expr as label
+use expr < 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 < 4k as retrieved evidence
+use scratch.summary < 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 < 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 < 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 < 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.
+
+```agentscript
+use docs.summary < 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

@@ -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
 
-        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

@@ -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
 
-        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

@@ -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
 
-        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

@@ -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
 
-        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

@@ -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
 
-        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.2",
+  "version": "0.1.4",
   "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/plan-execute.as

@@ -75,7 +75,7 @@ main agent PlanAndExecute {
         use goal
         use results.summary < 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
@@ -93,7 +93,7 @@ agent Planner {
         use input.problem
         use input.previous < 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
@@ -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
         }

package/tutorials/react.as

@@ -32,7 +32,7 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 1k
 
-        generate({ input: "Choose the next search focus", limit: 300 }) -> {
+        generate({ input: "Choose the next search focus", max_output: 300 }) -> {
             focus string
             why string
         }
@@ -60,7 +60,7 @@ main agent ResearchAgent {
 
         use raw
 
-        generate({ input: "Summarize the useful observation", limit: 400 }) -> {
+        generate({ input: "Summarize the useful observation", max_output: 400 }) -> {
             facts list[string]
             source string
         }
@@ -70,7 +70,7 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 1k
 
-        verdict = generate({ input: "Decide whether the observations are enough", limit: 200 }) -> {
+        verdict = generate({ input: "Decide whether the observations are enough", max_output: 200 }) -> {
             done boolean
         }
 
@@ -81,7 +81,7 @@ main agent ResearchAgent {
         use question
         use scratch.summary < 2k
 
-        generate({ input: "Answer using only the observations", limit: 800 }) -> {
+        generate({ input: "Answer using only the observations", max_output: 800 }) -> {
             ok boolean
             text string
             error string