@rong/agentscript 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to AgentScript will be documented in this file.
 
+## 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,13 +1,13 @@
 # AgentScript
 
 > **Agent context as code.**
-> `use` declares what the model can see.
-> `generate` defines the only LLM call site and its return shape.
+> `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
-return generate({ input: "Answer from observations" }) -> {
+use scratch.summary < 2k as observations
+generate({ input: "Answer from observations" }) -> {
     ok boolean
     text string
 }
@@ -61,10 +61,10 @@ 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
 
-        return generate({
+        generate({
             input: "Summarize the file for a busy teammate"
             limit: 1000
         }) -> {
@@ -93,7 +93,7 @@ Expected output (with mock LLM):
 
 With `--real-llm`, the fields are populated by the model.
 
-The block after `generate` is a return schema, not ordinary object construction.
+The optional block after `generate` is an output schema, not ordinary object construction.
 
 ## What problem it solves
 
@@ -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 *what* the LLM must return. 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.
+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
 
@@ -161,7 +161,7 @@ AgentScript doesn't hardcode agent patterns as keywords. You compose them from t
 | **Reflection / Self-Improvement** | `tutorials/self-improve.as` | Query past lessons → generate → reflect → persist new lessons |
 | **Multi-Agent** | `tutorials/plan-execute.as` | Independent agents with isolated context boundaries |
 
-Every pattern is explicit — which data enters the prompt, which tools each agent can use, and which output shape each LLM call must satisfy.
+Every pattern is explicit — which data enters the prompt, which tools each agent can use, and which output shape each LLM call must satisfy when one is declared.
 
 ## Language at a glance
 
@@ -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 {
@@ -191,13 +191,13 @@ main agent ResearchAgent {
             done = enough(input.question, scratch)
         }
 
-        return answer(input.question, scratch)
+        answer(input.question, scratch)
     }
 
     func answer(question, scratch) {
-        use question
-        use scratch.summary < 2k
-        return generate({ input: "Answer using only the observations" }) -> {
+        use question as user question
+        use scratch.summary < 2k as observations
+        generate({ input: "Answer using only the observations" }) -> {
             ok boolean
             text string
             error string
@@ -208,17 +208,18 @@ main agent ResearchAgent {
 
 ## Key ideas
 
-1. **`use` is explicit context** — nothing enters the LLM prompt unless `use`d
-2. **`generate` is the only LLM call site** — with a required input instruction and a return shape
-3. **Scope is context boundary** — functions, agents, and blocks isolate prompt visibility
-4. **Tools, memory, and files are imported resources** — with auditable access
-5. **Trace is built in** — every `generate` and `use` is recorded for debugging
+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
+5. **Tools, memory, and files are imported resources** — with auditable access
+6. **Trace is built in** — every `generate` and `use` is recorded for debugging
 
 ## Why not just Python or TypeScript?
 
 | | 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 |

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();
@@ -408,8 +421,7 @@ class Parser {
         this.consume("(");
         const options = this.parseGenerateOptions();
         this.consume(")");
-        this.consume("->");
-        const returnShape = this.parseShapeObject();
+        const returnShape = this.match("->") ? this.parseShapeObject() : undefined;
         return {
             kind: "GenerateExpr",
             options,
@@ -657,3 +669,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

@@ -19,7 +19,8 @@ export async function callAnthropic(request, parsed, options, fetchImpl, timeout
         "x-api-key": apiKey,
         "anthropic-version": "2023-06-01",
     });
-    return parseJsonText(readAnthropicText(response));
+    const text = readAnthropicText(response);
+    return request.returnShape ? parseJsonText(text) : text;
 }
 function readAnthropicText(value) {
     if (!value || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.content)) {

package/dist/providers/llm/ollama.js

@@ -4,16 +4,19 @@ export async function callOllama(request, parsed, fetchImpl, timeoutMs, baseUrl)
         model: parsed.model,
         stream: false,
         think: false,
-        format: request.builtContext.returnSchema,
         messages: [
             { role: "system", content: request.builtContext.system },
             { role: "user", content: request.builtContext.finalUserMessage },
         ],
     };
+    if (request.builtContext.returnSchema) {
+        body.format = request.builtContext.returnSchema;
+    }
     const maxTokens = budgetToTokenLimit(request);
     if (maxTokens) {
         body.options = { num_predict: maxTokens };
     }
     const response = await postJson(fetchImpl, `${baseUrl}/api/chat`, body, timeoutMs);
-    return parseJsonText(readPath(response, ["message", "content"]));
+    const text = readPath(response, ["message", "content"]);
+    return request.returnShape ? parseJsonText(text) : text;
 }

package/dist/providers/llm/openai.js

@@ -11,15 +11,17 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
             { role: "system", content: request.builtContext.system },
             { role: "user", content: request.builtContext.finalUserMessage },
         ],
-        response_format: {
+    };
+    if (request.builtContext.returnSchema) {
+        body.response_format = {
             type: "json_schema",
             json_schema: {
                 name: "agentscript_generate",
                 strict: true,
                 schema: request.builtContext.returnSchema,
             },
-        },
-    };
+        };
+    }
     const maxTokens = budgetToTokenLimit(request);
     if (maxTokens) {
         body.max_completion_tokens = maxTokens;
@@ -27,5 +29,6 @@ export async function callOpenAI(request, parsed, options, fetchImpl, timeoutMs,
     const response = await postJson(fetchImpl, `${baseUrl}/chat/completions`, body, timeoutMs, {
         authorization: `Bearer ${apiKey}`,
     });
-    return parseJsonText(readPath(response, ["choices", 0, "message", "content"]));
+    const text = readPath(response, ["choices", 0, "message", "content"]);
+    return request.returnShape ? parseJsonText(text) : text;
 }

package/dist/providers/mock/index.js

@@ -2,7 +2,7 @@ import { sanitizeForJson } from "../../runtime/json.js";
 import { buildValueFromShape } from "../../runtime/shape.js";
 export class MockLlmProvider {
     async generate(request) {
-        return buildValueFromShape(request.returnShape);
+        return request.returnShape ? buildValueFromShape(request.returnShape) : null;
     }
 }
 export class MockToolProvider {

package/dist/runtime/context.js

@@ -4,7 +4,7 @@ export function buildContext(input) {
     const instruction = sanitizeForJson(input.instruction);
     const instructionText = renderJson(instruction);
     const system = buildSystemPrompt(input.agentName, input.identity);
-    const returnSchema = shapeToSchema(input.returnShape);
+    const returnSchema = input.returnShape ? shapeToSchema(input.returnShape) : undefined;
     return {
         agentName: input.agentName,
         model: input.model,
@@ -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,12 +79,15 @@ 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);
-    sections.push("Return JSON matching this schema:", renderJson(returnSchema));
+    if (returnSchema) {
+        sections.push("Return JSON matching this schema:", renderJson(returnSchema));
+    }
     return sections.join("\n");
 }
 function renderJson(value) {
@@ -145,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),
@@ -153,7 +165,7 @@ export function builtContextToJson(context) {
             clippedSize: item.clippedSize,
         })),
         instruction: context.instruction,
-        returnSchema: context.returnSchema,
+        returnSchema: context.returnSchema ?? null,
         budget: budgetToJson(context.budget),
         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

@@ -58,8 +58,10 @@ export class GenerateRuntime {
                 continue;
             }
             try {
-                const result = coerceValueToShape(rawResult, expr.returnShape);
-                validateValueAgainstShape(result, expr.returnShape, expr.range);
+                const result = expr.returnShape ? coerceValueToShape(rawResult, expr.returnShape) : rawResult;
+                if (expr.returnShape) {
+                    validateValueAgainstShape(result, expr.returnShape, expr.range);
+                }
                 this.trace.push({
                     kind: "generate",
                     data: {

package/dist/runtime/interpreter.js

@@ -151,11 +151,8 @@ class Interpreter {
         this.callDepth += 1;
         const scope = await this.buildFunctionScope(agent, fn, args);
         try {
-            const signal = await this.executeBlock(fn.body, scope);
-            if (!signal) {
-                throw new RuntimeError(`Function '${agent.name}.${name}' completed without return`, fn.range);
-            }
-            return signal.value;
+            const signal = await this.executeBlock(fn.body, scope, true);
+            return signal?.value ?? null;
         }
         finally {
             this.callDepth -= 1;
@@ -194,8 +191,11 @@ class Interpreter {
     findFunction(agent, name) {
         return agent.functions.find((fn) => fn.name === name);
     }
-    async executeBlock(statements, scope) {
-        for (const stmt of statements) {
+    async executeBlock(statements, scope, allowFinalExpressionReturn = false) {
+        for (const [index, stmt] of statements.entries()) {
+            if (allowFinalExpressionReturn && index === statements.length - 1 && stmt.kind === "ExprStmt") {
+                return { kind: "return", value: await this.evaluator.evaluate(stmt.expr, scope) };
+            }
             const result = await this.executeStatement(stmt, scope);
             if (result)
                 return result;
@@ -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/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);
@@ -366,7 +369,9 @@ class Analyzer {
             this.checkExpression(expr.options.input, scope);
         }
         this.checkGenerateInput(expr);
-        this.checkShapeObject(expr.returnShape);
+        if (expr.returnShape) {
+            this.checkShapeObject(expr.returnShape);
+        }
         this.checkGenerateConfig("model", expr, scope);
         this.checkGenerateConfig("role", expr, scope);
         this.checkGenerateConfig("description", expr, scope);
@@ -499,6 +504,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",

package/docs/cn/context-engineering.md

@@ -32,7 +32,7 @@ func answer(question, scratch) {
     use question
     use scratch.summary < 2k
 
-    return generate({
+    generate({
         input: "Answer the question using collected facts"
         limit: 800
     }) -> {
@@ -61,7 +61,7 @@ main func(input) {
     scratch.add({ fact: "A" })
     scratch.add({ fact: "B" })
 
-    return generate({ input: "Answer from scratch" }) -> {
+    generate({ input: "Answer from scratch" }) -> {
         text string
     }
 }
@@ -119,12 +119,12 @@ AgentScript 中的作用域不仅是变量可见性规则，也是 prompt contex
 ```agentscript
 func caller(input) {
     use input.goal
-    return helper(input)
+    helper(input)
 }
 
 func helper(input) {
     use input.detail
-    return generate({ input: "Work on detail" }) -> {
+    generate({ input: "Work on detail" }) -> {
         ok boolean
     }
 }
@@ -235,10 +235,10 @@ Instruction 是本次 LLM 调用的局部任务，不应混入长期 context。
 
 ### Output contract
 
-Output contract 来自 `return shape`。
+Output contract 来自 `generate` 表达式上可选的 `-> { ... }` shape。
 
 ```agentscript
-return {
+generate({ input: "Answer" }) -> {
     ok boolean
     text string
     error string
@@ -260,7 +260,7 @@ use scratch.summary < 2k
 `generate({ limit: budget }) { ... }` 是 generation budget。
 
 ```agentscript
-return generate({
+generate({
     input: "Summarize"
     limit: 500
 }) -> {