@rong/agentscript 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to AgentScript will be documented in this file.
 
+## 0.1.4 - 2026-05-08
+
+### Added
+
+- Added `max_output` as the explicit `generate` output budget.
+- Added `temperature`, `think`, and `strict` generate options.
+- Added provider request mapping for generate provider hints.
+
+### Changed
+
+- Replaced generate `limit` usage with `max_output` in current docs, examples, tutorials, and fixtures.
+- Expanded English and Chinese `generate` design docs with configuration semantics.
+- Updated shape validation so `strict: true` disables coercion and rejects extra fields.
+
+## 0.1.3 - 2026-05-08
+
+### Added
+
+- Added final expression return for functions.
+- Added literal context labels with `use context as label`.
+- Added agent role and description to prompt identity construction.
+- Added trace and built context output for context labels.
+
+### Changed
+
+- Updated README, examples, and language references for labeled context usage.
+
 ## 1.0.0 - 2026-05-07
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # AgentScript
 
 > **Agent context as code.**
-> `use` declares what the model can see.
+> `use` declares what the model can see, with optional labels for prompt sections.
 > `generate` defines the only LLM call site and optional output shape.
 > Zero runtime dependencies. TypeScript-powered.
 
 ```agentscript
-use scratch.summary < 2k
+use scratch.summary < 2k as observations
 generate({ input: "Answer from observations" }) -> {
     ok boolean
     text string
@@ -61,12 +61,12 @@ main agent FileSummarizer {
 
     main func(input { path string }) {
         content = File.read({ 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
+            max_output: 1000
         }) -> {
             title string
             summary string
@@ -113,7 +113,7 @@ It is a small language for one thing:
 
 > making LLM prompt context explicit, scoped, typed, traceable, and compilable.
 
-It gives you two things that general-purpose languages don't: a first-class `use` keyword that declares *which* data enters the LLM prompt, and a first-class `generate` expression that defines an LLM call with an optional output contract. Everything else — variables, functions, agents, imports, loops — exists to support this core workflow. Scopes enforce context boundaries naturally: what's `use`d in one function stays there; child scopes inherit but never leak upward. Functions can also return their final top-level expression directly, which keeps typical LLM workflows concise.
+It gives you two things that general-purpose languages don't: a first-class `use` keyword that declares *which* data enters the LLM prompt and what role it plays via `as label`, and a first-class `generate` expression that defines an LLM call with an optional output contract. Everything else — variables, functions, agents, imports, loops — exists to support this core workflow. Scopes enforce context boundaries naturally: what's `use`d in one function stays there; child scopes inherit but never leak upward. Functions can also return their final top-level expression directly, which keeps typical LLM workflows concise.
 
 ## How it works
 
@@ -178,10 +178,10 @@ main agent ResearchAgent {
     main func(input {
         question string
     }) {
-        use input.question
+        use input.question as user question
 
         scratch = []
-        use scratch.summary < 2k
+        use scratch.summary < 2k as observations
 
         done = false
         loop until done < 6 {
@@ -195,8 +195,8 @@ main agent ResearchAgent {
     }
 
     func answer(question, scratch) {
-        use question
-        use scratch.summary < 2k
+        use question as user question
+        use scratch.summary < 2k as observations
         generate({ input: "Answer using only the observations" }) -> {
             ok boolean
             text string
@@ -208,7 +208,7 @@ main agent ResearchAgent {
 
 ## Key ideas
 
-1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d
+1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d; `as label` names the context section
 2. **`generate` is the only LLM call site** — with a required input instruction and optional output shape
 3. **Final expression return keeps flows concise** — a function returns its final top-level expression
 4. **Scope is context boundary** — functions, agents, and blocks isolate prompt visibility
@@ -219,7 +219,7 @@ main agent ResearchAgent {
 
 | | Python / TypeScript | AgentScript |
 |---|---|---|
-| Context management | Implicit (string concatenation, array append) | Explicit (`use` declaration) |
+| Context management | Implicit (string concatenation, array append) | Explicit (`use` declaration, optional `as label`) |
 | LLM call site | Anywhere in the code | One `generate` expression |
 | Context isolation | Manual discipline | Scope-inherited, auto-isolated |
 | Trace / audit | External tooling needed | Built-in, per-call |
@@ -254,8 +254,8 @@ agentscript examples/review.as --quiet               # value only, no trace
 
 | Language | Links |
 |----------|-------|
-| English | [Language Reference](docs/en/language.md) · [Context Engineering](docs/en/context-engineering.md) · [Design History](docs/design-history/) |
-| 中文 | [README-CN](./README-CN.md) · [语言参考](docs/cn/language.md) · [Context Engineering](docs/cn/context-engineering.md) |
+| English | [Language Reference](docs/en/language.md) · [Context Engineering](docs/en/context-engineering.md) · [`use ... as ...`](docs/en/use-as.md) · [`generate`](docs/en/generate.md) · [Design History](docs/design-history/) |
+| 中文 | [README-CN](./README-CN.md) · [语言参考](docs/cn/language.md) · [Context Engineering](docs/cn/context-engineering.md) · [`use ... as ...`](docs/cn/use-as.md) · [`generate`](docs/cn/generate.md) |
 
 ### Design principles
 

package/dist/parser/parser.js

@@ -176,13 +176,26 @@ class Parser {
         const start = this.consume("use").range.start;
         const value = this.parseLogicalOr();
         const budget = this.match("<") ? this.parseBudget() : undefined;
+        const label = this.match("as") ? this.parseUseLabel() : undefined;
         return {
             kind: "UseStmt",
             value,
             budget,
+            label,
             range: { start, end: this.previous().range.end }
         };
     }
+    parseUseLabel() {
+        const tokens = [];
+        const line = this.previous().range.start.line;
+        while (!this.isAtEnd() && !this.check("}") && this.peek().range.start.line === line) {
+            tokens.push(this.advance());
+        }
+        if (tokens.length === 0) {
+            throw this.error("Expected context label after 'as'");
+        }
+        return stringifyLabelTokens(tokens);
+    }
     parseConfigValue(key) {
         if (key === "model") {
             return this.parsePostfix();
@@ -421,16 +434,19 @@ class Parser {
         const properties = [];
         let input;
         let attempts;
-        let limit;
+        let maxOutput;
+        let temperature;
+        let think;
+        let strict;
         let debug;
         while (!this.check("}") && !this.isAtEnd()) {
             const propStart = this.peek().range.start;
             const key = this.consumeObjectKey();
             this.consume(":");
             let value;
-            if (key === "limit") {
-                const token = this.consumeKind("number", "Expected generate limit");
-                limit = this.parseBudgetToken(token);
+            if (key === "max_output") {
+                const token = this.consumeKind("number", "Expected generate max_output");
+                maxOutput = this.parseBudgetToken(token);
                 value = {
                     kind: "NumberExpr",
                     value: Number.parseFloat(token.value),
@@ -453,6 +469,15 @@ class Parser {
             else if (key === "attempts" && value.kind === "NumberExpr") {
                 attempts = value;
             }
+            else if (key === "temperature" && value.kind === "NumberExpr") {
+                temperature = value;
+            }
+            else if (key === "think" && (value.kind === "BooleanExpr" || value.kind === "StringExpr")) {
+                think = value;
+            }
+            else if (key === "strict" && value.kind === "BooleanExpr") {
+                strict = value;
+            }
             else if (key === "debug" && value.kind === "BooleanExpr") {
                 debug = value;
             }
@@ -464,7 +489,10 @@ class Parser {
             properties,
             input,
             attempts,
-            limit,
+            maxOutput,
+            temperature,
+            think,
+            strict,
             debug,
             range: { start, end: this.previous().range.end }
         };
@@ -656,3 +684,15 @@ class Parser {
 function isImportResourceKind(value) {
     return IMPORT_RESOURCE_KINDS.has(value);
 }
+function stringifyLabelTokens(tokens) {
+    let label = tokens[0]?.value ?? "";
+    for (let index = 1; index < tokens.length; index += 1) {
+        const previous = tokens[index - 1];
+        const current = tokens[index];
+        if (current.range.start.column > previous.range.end.column) {
+            label += " ";
+        }
+        label += current.value;
+    }
+    return label;
+}

package/dist/providers/llm/anthropic.js

@@ -5,7 +5,7 @@ export async function callAnthropic(request, parsed, options, fetchImpl, timeout
     if (!apiKey) {
         throw new RuntimeError("ANTHROPIC_API_KEY is required for anthropic:// models");
     }
-    const response = await postJson(fetchImpl, `${baseUrl}/messages`, {
+    const body = {
         model: parsed.model,
         max_tokens: budgetToTokenLimit(request) ?? 1024,
         system: request.builtContext.system,
@@ -15,7 +15,11 @@ export async function callAnthropic(request, parsed, options, fetchImpl, timeout
                 content: request.builtContext.finalUserMessage,
             },
         ],
-    }, timeoutMs, {
+    };
+    if (request.temperature !== undefined) {
+        body.temperature = request.temperature;
+    }
+    const response = await postJson(fetchImpl, `${baseUrl}/messages`, body, timeoutMs, {
         "x-api-key": apiKey,
         "anthropic-version": "2023-06-01",
     });

package/dist/providers/llm/ollama.js

@@ -3,7 +3,7 @@ export async function callOllama(request, parsed, fetchImpl, timeoutMs, baseUrl)
     const body = {
         model: parsed.model,
         stream: false,
-        think: false,
+        think: request.think ?? false,
         messages: [
             { role: "system", content: request.builtContext.system },
             { role: "user", content: request.builtContext.finalUserMessage },
@@ -13,8 +13,15 @@ export async function callOllama(request, parsed, fetchImpl, timeoutMs, baseUrl)
         body.format = request.builtContext.returnSchema;
     }
     const maxTokens = budgetToTokenLimit(request);
+    const options = {};
     if (maxTokens) {
-        body.options = { num_predict: maxTokens };
+        options.num_predict = maxTokens;
+    }
+    if (request.temperature !== undefined) {
+        options.temperature = request.temperature;
+    }
+    if (Object.keys(options).length > 0) {
+        body.options = options;
     }
     const response = await postJson(fetchImpl, `${baseUrl}/api/chat`, body, timeoutMs);
     const text = readPath(response, ["message", "content"]);

package/dist/providers/llm/openai.js

@@ -17,11 +17,18 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
             type: "json_schema",
             json_schema: {
                 name: "agentscript_generate",
-                strict: true,
+                strict: request.strict,
                 schema: request.builtContext.returnSchema,
             },
         };
     }
+    if (request.temperature !== undefined) {
+        body.temperature = request.temperature;
+    }
+    const reasoningEffort = openAIReasoningEffort(request.think);
+    if (reasoningEffort) {
+        body.reasoning_effort = reasoningEffort;
+    }
     const maxTokens = budgetToTokenLimit(request);
     if (maxTokens) {
         body.max_completion_tokens = maxTokens;
@@ -32,3 +39,10 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
     const text = readPath(response, ["choices", 0, "message", "content"]);
     return request.returnShape ? parseJsonText(text) : text;
 }
+function openAIReasoningEffort(think) {
+    if (think === true)
+        return "medium";
+    if (think === "low" || think === "medium" || think === "high")
+        return think;
+    return undefined;
+}

package/dist/providers/llm/shared.js

@@ -1,12 +1,12 @@
 import { RuntimeError } from "../../runtime/errors.js";
 export function budgetToTokenLimit(request) {
-    if (!request.budget) {
+    if (!request.maxOutput) {
         return undefined;
     }
-    if (request.budget.unit === "k") {
-        return Math.max(1, Math.floor(request.budget.amount * 1000));
+    if (request.maxOutput.unit === "k") {
+        return Math.max(1, Math.floor(request.maxOutput.amount * 1000));
     }
-    return Math.max(1, Math.floor(request.budget.amount));
+    return Math.max(1, Math.floor(request.maxOutput.amount));
 }
 export async function postJson(fetchImpl, url, body, timeoutMs, headers = {}) {
     const controller = new AbortController();

package/dist/runtime/context.js

@@ -14,7 +14,7 @@ export function buildContext(input) {
         instruction,
         instructionText,
         returnSchema,
-        budget: input.budget,
+        maxOutput: input.maxOutput,
         finalUserMessage: buildFinalUserMessage(context, instructionText, returnSchema),
     };
 }
@@ -51,6 +51,7 @@ function buildContextItem(item, index) {
     return {
         index,
         source: item.source,
+        label: item.label,
         value: clipped.value,
         text: clipped.text,
         budget: item.budget,
@@ -60,8 +61,15 @@ function buildContextItem(item, index) {
     };
 }
 function buildSystemPrompt(agentName, identity) {
-    const lines = [`You are ${agentName}.`];
+    const role = typeof identity.role === "string" ? identity.role : agentName;
+    const lines = [`You are ${role}.`];
+    if (typeof identity.description === "string") {
+        lines.push(identity.description);
+    }
     for (const [key, value] of Object.entries(identity)) {
+        if (key === "role" || key === "description") {
+            continue;
+        }
         lines.push(`${key}: ${renderJson(value)}`);
     }
     return lines.join("\n");
@@ -71,8 +79,9 @@ function buildFinalUserMessage(context, instructionText, returnSchema) {
     if (context.length > 0) {
         sections.push("Context:");
         for (const item of context) {
-            const label = item.source ? `${item.source}:\n` : "";
-            sections.push(`[${item.index}] ${label}${item.text}`);
+            const label = item.label ?? String(item.index);
+            const source = item.source ? `source: ${item.source}\n` : "";
+            sections.push(`[${label}]\n${source}${item.text}`);
         }
     }
     sections.push("Instruction:", instructionText);
@@ -147,6 +156,7 @@ export function builtContextToJson(context) {
         context: context.context.map((item) => ({
             index: item.index,
             source: item.source ?? null,
+            label: item.label ?? null,
             value: item.value,
             text: item.text,
             budget: budgetToJson(item.budget),
@@ -156,7 +166,7 @@ export function builtContextToJson(context) {
         })),
         instruction: context.instruction,
         returnSchema: context.returnSchema ?? null,
-        budget: budgetToJson(context.budget),
+        maxOutput: budgetToJson(context.maxOutput),
         finalUserMessage: context.finalUserMessage,
     };
 }

package/dist/runtime/evaluator.js

@@ -80,6 +80,7 @@ export class Evaluator {
         for (const item of scope.visibleUses()) {
             uses.push({
                 source: item.source,
+                label: item.label,
                 value: await this.evaluate(item.expr, item.scope),
                 budget: item.budget,
             });

package/dist/runtime/generate.js

@@ -29,7 +29,7 @@ export class GenerateRuntime {
                 instruction,
                 returnShape: expr.returnShape,
                 uses: context,
-                budget: options.limit,
+                maxOutput: options.maxOutput,
             });
             if (options.debug) {
                 writeDebugPrompt(agent.name, attempt, builtContext);
@@ -44,7 +44,11 @@ export class GenerateRuntime {
                     returnShape: expr.returnShape,
                     context,
                     builtContext,
-                    budget: options.limit,
+                    maxOutput: options.maxOutput,
+                    temperature: options.temperature,
+                    think: options.think,
+                    strict: options.strict,
+                    debug: options.debug,
                 });
             }
             catch (error) {
@@ -58,18 +62,27 @@ export class GenerateRuntime {
                 continue;
             }
             try {
-                const result = expr.returnShape ? coerceValueToShape(rawResult, expr.returnShape) : rawResult;
+                const result = expr.returnShape && !options.strict ? coerceValueToShape(rawResult, expr.returnShape) : rawResult;
                 if (expr.returnShape) {
-                    validateValueAgainstShape(result, expr.returnShape, expr.range);
+                    validateValueAgainstShape(result, expr.returnShape, expr.range, { rejectExtraFields: options.strict });
                 }
                 this.trace.push({
                     kind: "generate",
                     data: {
                         instruction: sanitizeForJson(options.input),
+                        config: {
+                            maxOutput: budgetToJson(options.maxOutput),
+                            attempts: options.attempts,
+                            temperature: options.temperature ?? null,
+                            think: options.think ?? false,
+                            strict: options.strict,
+                            debug: options.debug,
+                        },
                         attempts: attempt,
-                        budget: budgetToJson(options.limit),
+                        maxOutput: budgetToJson(options.maxOutput),
                         debug: options.debug,
                         context: builtContextToJson(builtContext),
+                        validation: expr.returnShape ? { ok: true, strict: options.strict } : null,
                         result: sanitizeForJson(result),
                     },
                 });
@@ -99,7 +112,10 @@ export class GenerateRuntime {
         return {
             input: await this.host.evaluate(expr.options.input, scope),
             attempts,
-            limit: expr.options.limit,
+            maxOutput: expr.options.maxOutput,
+            temperature: expr.options.temperature?.value,
+            think: expr.options.think?.value,
+            strict: expr.options.strict?.value ?? false,
             debug: expr.options.debug?.value ?? false,
         };
     }

package/dist/runtime/interpreter.js

@@ -209,8 +209,11 @@ class Interpreter {
                 return undefined;
             case "UseStmt": {
                 const source = formatExpressionSource(stmt.value);
-                scope.addUse(stmt.value, source, stmt.budget);
-                this.trace.push({ kind: "use", data: { source, budget: budgetToJson(stmt.budget) } });
+                scope.addUse(stmt.value, source, stmt.budget, stmt.label);
+                this.trace.push({
+                    kind: "use",
+                    data: { source, label: stmt.label ?? null, budget: budgetToJson(stmt.budget) },
+                });
                 return undefined;
             }
             case "AssignStmt": {

package/dist/runtime/scope.js

@@ -29,8 +29,8 @@ export class RuntimeScope {
         }
         this.define(name, value);
     }
-    addUse(expr, source, budget) {
-        this.uses.push({ expr, source, budget, scope: this });
+    addUse(expr, source, budget, label) {
+        this.uses.push({ expr, source, budget, label, scope: this });
     }
     setConfig(name, value) {
         this.config.set(name, value);

package/dist/runtime/shape.js

@@ -7,14 +7,16 @@ export function buildValueFromShape(shape) {
     }
     return result;
 }
-export function validateValueAgainstShape(value, shape, range) {
+export function validateValueAgainstShape(value, shape, range, options = {}) {
     if (!isObject(value)) {
         throw new RuntimeError("LLM result must be an object matching the generate return shape", range);
     }
     const allowedFields = new Set(shape.fields.map((field) => field.name));
-    for (const key of Object.keys(value)) {
-        if (!allowedFields.has(key)) {
-            throw new RuntimeError(`LLM result contains unexpected field '${key}'`, range);
+    if (options.rejectExtraFields) {
+        for (const key of Object.keys(value)) {
+            if (!allowedFields.has(key)) {
+                throw new RuntimeError(`LLM result contains unexpected field '${key}'`, range);
+            }
         }
     }
     for (const field of shape.fields) {

package/dist/semantic/analyzer.js

@@ -171,6 +171,9 @@ class Analyzer {
                 if (stmt.budget && stmt.budget.amount <= 0) {
                     this.error("INVALID_BUDGET", "Budget amount must be greater than 0", stmt.range);
                 }
+                if (stmt.label && RESERVED_CONTEXT_LABELS.has(stmt.label)) {
+                    this.error("RESERVED_CONTEXT_LABEL", `Context label '${stmt.label}' is reserved`, stmt.range);
+                }
                 break;
             case "AssignStmt":
                 this.checkAssignment(stmt, scope);
@@ -392,9 +395,26 @@ class Analyzer {
                     this.error("INVALID_GENERATE_ATTEMPTS", "generate attempts must be a positive integer", property.value.range);
                 }
             }
-            else if (property.key === "limit") {
-                if (!expr.options.limit || expr.options.limit.amount <= 0) {
-                    this.error("INVALID_GENERATE_LIMIT", "generate limit must be a positive budget", property.value.range);
+            else if (property.key === "max_output") {
+                if (!expr.options.maxOutput || expr.options.maxOutput.amount <= 0) {
+                    this.error("INVALID_GENERATE_MAX_OUTPUT", "generate max_output must be a positive budget", property.value.range);
+                }
+            }
+            else if (property.key === "temperature") {
+                if (property.value.kind !== "NumberExpr") {
+                    this.error("INVALID_GENERATE_TEMPERATURE", "generate temperature must be a number", property.value.range);
+                }
+            }
+            else if (property.key === "think") {
+                const validThinkString = property.value.kind === "StringExpr" &&
+                    ["auto", "low", "medium", "high"].includes(property.value.value);
+                if (property.value.kind !== "BooleanExpr" && !validThinkString) {
+                    this.error("INVALID_GENERATE_THINK", "generate think must be a boolean or one of auto, low, medium, high", property.value.range);
+                }
+            }
+            else if (property.key === "strict") {
+                if (property.value.kind !== "BooleanExpr") {
+                    this.error("INVALID_GENERATE_STRICT", "generate strict must be a boolean", property.value.range);
                 }
             }
             else if (property.key === "debug") {
@@ -501,6 +521,7 @@ class Analyzer {
 const IMPORTED_BINDING_KINDS = new Set(["tool", "llm", "file", "agent", "memory"]);
 const NON_CONTEXT_BINDING_KINDS = new Set(["tool", "llm", "agent", "function", "memory"]);
 const VALID_MEMORY_METHODS = new Set(["add", "query"]);
+const RESERVED_CONTEXT_LABELS = new Set(["system", "assistant", "tool", "developer"]);
 function functionBinding(agentName, fn) {
     return {
         kind: "function",