@rong/agentscript 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to AgentScript will be documented in this file.
+
+## 1.0.0 - 2026-05-07
+
+### Added
+
+- Initial public release of AgentScript.
+- Parser, semantic analyzer, and interpreter for `.as` programs.
+- CLI support for parse, check, execute, REPL, trace, quiet, and verbose modes.
+- LLM providers for OpenAI, Anthropic, and Ollama protocol URIs.
+- Tool providers for Find, Grep, Sed, File, Env, and Http operations.
+- Explicit prompt context model with `use`, scoped context inheritance, and context budgets.
+- `generate` with structured output shapes, validation, limited repair attempts, and trace output.
+- Agent/function composition including cross-agent calls and imported agents.
+- Control flow support for `if`/`else`, `loop until`, `repeat`, and `for item in list < n`.
+- List and JSON helpers including item access, `.length`, `.add(value)`, and `.summary`.
+- File import support for static context inputs.
+- Memory imports with explicit `add` and `query` operations.
+- File JSONL and SQLite memory backends.
+- Tutorials, examples, regression fixtures, and automated tests.

package/INSTALL.md

@@ -0,0 +1,92 @@
+# Install AgentScript
+
+AgentScript is distributed as an npm package and can also be run from source.
+
+## Requirements
+
+- Node.js compatible with the runtime features used by this project.
+- npm.
+- Optional: Ollama, OpenAI, or Anthropic credentials when running with `--real-llm`.
+
+The current development setup uses Node.js 25 types and the SQLite memory backend uses Node's built-in `node:sqlite` module.
+
+## Install from npm
+
+After the package is published:
+
+```bash
+npm install -g agentscript
+agentscript examples/review.as --input '{"path":"src"}'
+```
+
+## Run with npx
+
+After the package is published:
+
+```bash
+npx agentscript examples/review.as --input '{"path":"src"}'
+```
+
+## Run from source
+
+```bash
+git clone https://github.com/<owner>/<repo>.git
+cd <repo>
+npm install
+npm run build
+npm run execute -- examples/review.as --input '{"path":"src"}'
+```
+
+During local development, prefer:
+
+```bash
+npm run execute -- tutorials/react.as --input '{"question":"What is AgentScript?"}'
+npm run check -- examples/review.as
+npm run parse -- examples/review.as
+```
+
+## Real LLM providers
+
+By default, AgentScript uses a mock LLM provider for local flow checks. Add `--real-llm` to call a real provider.
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="..."
+agentscript examples/review.as --input '{"path":"src"}' --real-llm
+```
+
+Use an AgentScript import such as:
+
+```agentscript
+import llm OpenAI from "openai://gpt-4.1-mini"
+```
+
+### Anthropic
+
+```bash
+export ANTHROPIC_API_KEY="..."
+agentscript examples/review.as --input '{"path":"src"}' --real-llm
+```
+
+Use an AgentScript import such as:
+
+```agentscript
+import llm Claude from "anthropic://claude-sonnet-4-0"
+```
+
+### Ollama
+
+Run Ollama locally, then use an import such as:
+
+```agentscript
+import llm Qwen from "ollama://localhost:11434/qwen3.6"
+```
+
+## Validate a checkout
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rong Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# AgentScript
+
+> **Prompt context as a first-class citizen.**  
+> `use` declares what the model sees. `generate` defines what it returns.  
+> Zero runtime dependencies. TypeScript-powered.
+
+```agentscript
+use scratch.summary < 2k
+return generate({ input: "Answer from observations" }) {
+    return { ok boolean, text string }
+}
+```
+
+[![License: ISC](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+![Node >= 25](https://img.shields.io/badge/node-%3E%3D25-green)
+
+[中文版](./README-CN.md)
+
+LLMs are stateless by nature. Each call is a fresh start. To give an agent continuity of thought, every input must be carefully assembled — what researchers and practitioners call context engineering.
+
+After building agents with Python and TypeScript, the author kept running into the same problem: prompt context management. What data actually reaches the LLM? Where does one agent's context end and another's begin? How do you audit what the model saw?
+
+AgentScript was designed to solve this — not as a general-purpose language, nor a declarative config, nor a prompt template, but as a **DSL** that mixes imperative control flow with explicit, scope-governed context declarations.
+
+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.
+
+The result is a language purpose-built for composing agent patterns — ReAct, Plan-and-Execute, Reflection, Multi-Agent — where prompt context is always visible, auditable, and under your control.
+
+## How it works
+
+```mermaid
+graph LR
+    A[".as source"] --> B["Parser"]
+    B --> C["AST"]
+    C --> D["Semantic Analyzer"]
+    D --> E["Runtime"]
+    E --> F["LLM Provider<br/>(OpenAI / Anthropic / Ollama)"]
+    E --> G["Tools<br/>(Find / Grep / File / HTTP / ...)"]
+    E --> H["Memory<br/>(JSONL / SQLite)"]
+    E --> I["Trace Output"]
+```
+
+## Agent patterns as composable primitives
+
+AgentScript doesn't hardcode agent patterns as keywords. You compose them from the same primitives:
+
+| Pattern | Tutorial | What it demonstrates |
+|---------|----------|---------------------|
+| **ReAct** | `tutorials/react.as` | Reason → Act → Observe loop with explicit context |
+| **Plan-and-Execute** | `tutorials/plan-execute.as` | Generate plan, execute steps, verify, re-plan on failure |
+| **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.
+
+## Install
+
+```bash
+npm install -g agentscript
+```
+
+Or run without installing:
+
+```bash
+npx agentscript examples/review.as --input '{"path":"src"}'
+```
+
+## Quick start
+
+```bash
+# Run with mock LLM (default, no API key needed)
+agentscript examples/summarize.as --input '{"path":"README.md"}'
+
+# Run with real LLM
+agentscript examples/summarize.as --input '{"path":"README.md"}' --real-llm
+```
+
+The `summarize.as` file reads a local file, includes it in the LLM context, and returns a structured summary:
+
+```agentscript
+-- examples/summarize.as
+import llm Qwen from "ollama://localhost:11434/qwen3.6"
+import tool File from "file://workspace"
+
+main agent FileSummarizer {
+    model Qwen
+    role "Technical Writer"
+    description "Read one local file and produce a useful structured summary."
+
+    main func(input { path string }) {
+        content = File.read({ path: input.path })
+        use input.path
+        use content < 8k
+
+        return generate({
+            input: "Summarize the file for a busy teammate"
+            limit: 1000
+        }) {
+            return {
+                title string
+                summary string
+                key_points list[string]
+                action_items list[string]
+            }
+        }
+    }
+}
+```
+
+Expected output (with mock LLM):
+
+```json
+{
+  "value": {
+    "title": "",
+    "summary": "",
+    "key_points": [],
+    "action_items": []
+  },
+  "trace": [ ... ]
+}
+```
+
+With `--real-llm`, the fields are populated by the model.
+
+## Language at a glance
+
+```agentscript
+import llm Qwen from "ollama://localhost:11434/qwen3.6"
+import tool Search from "mcp://tools/search"
+import memory Lessons from "file://./.agentscript/lessons.jsonl"
+
+main agent ResearchAgent {
+    model Qwen
+    role "Senior Researcher"
+    description "Answer questions with search and structured reasoning."
+
+    main func(input {
+        question string
+    }) {
+        use input.question
+
+        scratch = []
+        use scratch.summary < 2k
+
+        done = false
+        loop until done < 6 {
+            thought = reason(input.question, scratch)
+            obs = Search.search(thought.focus)
+            scratch.add(obs)
+            done = enough(input.question, scratch)
+        }
+
+        return answer(input.question, scratch)
+    }
+
+    func answer(question, scratch) {
+        use question
+        use scratch.summary < 2k
+        return generate({ input: "Answer using only the observations" }) {
+            return {
+                ok boolean
+                text string
+                error string
+            }
+        }
+    }
+}
+```
+
+## 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
+
+## Why not just Python or TypeScript?
+
+| | Python / TypeScript | AgentScript |
+|---|---|---|
+| Context management | Implicit (string concatenation, array append) | Explicit (`use` declaration) |
+| 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 |
+
+Python and TypeScript are excellent general-purpose tools, but they have no concept of "prompt context" as a language primitive. Every agent project reinvents the same patterns. AgentScript bakes them in.
+
+## CLI
+
+```bash
+agentscript examples/review.as                       # run with mock LLM
+agentscript examples/review.as --check               # parse + semantic check only
+agentscript examples/review.as --parse               # parse and output AST
+agentscript examples/review.as --trace pretty        # human-readable trace
+agentscript examples/review.as --quiet               # value only, no trace
+```
+
+| Option | Description |
+|--------|-------------|
+| `--input '<json>'` | JSON input for the entry function |
+| `--input-file <path>` | Read input from a JSON file |
+| `--agent <name>` | Select a specific entry agent |
+| `--function <name>` | Select a specific entry function |
+| `--check` | Parse + semantic analysis (no execution) |
+| `--parse` | Parse and output AST as JSON |
+| `--real-llm` | Use real LLM provider instead of mock |
+| `--trace <file>` | Write execution trace to file |
+| `--trace pretty` | Print human-readable trace |
+| `--verbose` | Print detailed trace |
+| `--quiet` | Output only the final value |
+
+## Documentation
+
+| 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) |
+
+### Design principles
+
+- Context is explicit: ordinary variables, tool results, memory records, and trace events never enter prompts unless selected with `use`.
+- Scope controls variable lifetime, context inheritance, and prompt exposure.
+- LLM, tool, file, agent, and memory imports are runtime capabilities with explicit boundaries.
+- Pattern names such as planner, executor, verifier, reflect, improve, and evolve are ordinary identifiers.
+- Trace is for debugging and audit; it is not prompt context.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+Zero runtime dependencies. Built with TypeScript.
+
+## License
+
+MIT

package/dist/ast/constants.js

@@ -0,0 +1 @@
+export const SHAPE_TYPE_NAMES = new Set(["string", "number", "boolean", "json", "list"]);

package/dist/ast/format.js

@@ -0,0 +1,41 @@
+import { assertNever } from "../utils/assert.js";
+export function formatExpressionSource(expr) {
+    switch (expr.kind) {
+        case "IdentifierExpr":
+            return expr.name;
+        case "StringExpr":
+            return JSON.stringify(expr.value);
+        case "NumberExpr":
+            return expr.raw;
+        case "BooleanExpr":
+            return String(expr.value);
+        case "NullExpr":
+            return "none";
+        case "ListExpr":
+            return `[${formatItems(expr.items)}]`;
+        case "ObjectExpr":
+            return `{ ${formatProperties(expr.properties)} }`;
+        case "ShapeObjectExpr":
+            return "{ shape }";
+        case "MemberExpr":
+            return `${formatExpressionSource(expr.object)}.${expr.property}`;
+        case "IndexExpr":
+            return `${formatExpressionSource(expr.object)}[${formatExpressionSource(expr.index)}]`;
+        case "UnaryExpr":
+            return `${expr.operator} ${formatExpressionSource(expr.value)}`;
+        case "BinaryExpr":
+            return `${formatExpressionSource(expr.left)} ${expr.operator} ${formatExpressionSource(expr.right)}`;
+        case "CallExpr":
+            return `${formatExpressionSource(expr.callee)}(${formatItems(expr.args)})`;
+        case "GenerateExpr":
+            return `generate({ ${formatProperties(expr.options.properties)} })`;
+        default:
+            assertNever(expr);
+    }
+}
+function formatItems(items) {
+    return items.map(formatExpressionSource).join(", ");
+}
+function formatProperties(properties) {
+    return properties.map((p) => `${p.key}: ${formatExpressionSource(p.value)}`).join(", ");
+}

package/dist/ast/types.js

@@ -0,0 +1 @@
+export {};

package/dist/bin/agentscript.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stdin as inputStream, stdout as outputStream } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { executeAgent } from "../runtime/interpreter.js";
+import { loadProgram } from "../runtime/loader.js";
+import { ProtocolLlmProvider } from "../providers/llm/index.js";
+import { sanitizeForJson } from "../runtime/json.js";
+import { formatTrace } from "../runtime/trace.js";
+import { analyze } from "../semantic/analyzer.js";
+import { formatSemanticDiagnostics } from "../semantic/diagnostics.js";
+import { parseInteractiveInputValue, parseJsonObjectInput } from "./input.js";
+import { runRepl } from "./repl.js";
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        if (argv.length === 0) {
+            return runRepl();
+        }
+        const options = parseArgs(argv);
+        if (options.help) {
+            printUsage(console.log);
+            return 0;
+        }
+        if (options.version) {
+            console.log(readPackageVersion());
+            return 0;
+        }
+        if (!options.file) {
+            printUsage(console.error);
+            return 1;
+        }
+        if (options.parse && options.check) {
+            throw new Error("Use either --parse or --check, not both");
+        }
+        if (options.parse) {
+            return runParse(options);
+        }
+        if (options.check) {
+            return runCheck(options);
+        }
+        return await runAgent(options);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+function parseArgs(argv) {
+    const options = {
+        check: false,
+        help: false,
+        parse: false,
+        quiet: false,
+        realLlm: false,
+        tracePretty: false,
+        verbose: false,
+        version: false
+    };
+    const positional = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        switch (arg) {
+            case "--agent":
+                options.agentName = readOptionValue(argv, ++index, arg);
+                break;
+            case "--function":
+                options.functionName = readOptionValue(argv, ++index, arg);
+                break;
+            case "--input":
+                options.input = readOptionValue(argv, ++index, arg);
+                break;
+            case "--input-file":
+                options.inputFile = readOptionValue(argv, ++index, arg);
+                break;
+            case "--check":
+                options.check = true;
+                break;
+            case "--help":
+            case "-h":
+                options.help = true;
+                break;
+            case "--parse":
+                options.parse = true;
+                break;
+            case "--quiet":
+                options.quiet = true;
+                break;
+            case "--real-llm":
+                options.realLlm = true;
+                break;
+            case "--version":
+            case "-v":
+                options.version = true;
+                break;
+            case "--trace":
+                {
+                    const value = readOptionValue(argv, ++index, arg);
+                    if (value === "pretty") {
+                        options.tracePretty = true;
+                    }
+                    else {
+                        options.traceFile = value;
+                    }
+                }
+                break;
+            case "--verbose":
+                options.verbose = true;
+                break;
+            default:
+                if (arg.startsWith("--")) {
+                    throw new Error(`Unknown option '${arg}'`);
+                }
+                positional.push(arg);
+        }
+    }
+    options.file = positional[0];
+    if (positional.length > 1) {
+        throw new Error("Unexpected positional argument. Use --input to pass input JSON.");
+    }
+    if (options.quiet && (options.verbose || options.tracePretty)) {
+        throw new Error("Use either --quiet or verbose trace output, not both");
+    }
+    return options;
+}
+function readOptionValue(args, index, option) {
+    const value = args[index];
+    if (!value) {
+        throw new Error(`Expected value after ${option}`);
+    }
+    return value;
+}
+function runParse(options) {
+    printJson(loadCliProgram(options));
+    return 0;
+}
+function runCheck(options) {
+    const result = analyze(loadCliProgram(options));
+    if (result.diagnostics.length > 0) {
+        console.error(formatSemanticDiagnostics(result.diagnostics));
+    }
+    return result.diagnostics.some((diagnostic) => diagnostic.severity === "error") ? 1 : 0;
+}
+async function runAgent(options) {
+    const input = readInput(options);
+    const inputProvider = terminalInputProvider();
+    const result = await executeAgent(loadCliProgram(options), input, {
+        agentName: options.agentName,
+        functionName: options.functionName,
+        inputProvider,
+        llmProvider: options.realLlm ? new ProtocolLlmProvider() : undefined,
+        sourcePath: options.file,
+    }).finally(() => inputProvider?.close?.());
+    if (options.traceFile) {
+        writeFileSync(options.traceFile, `${JSON.stringify(result.trace, null, 2)}\n`);
+    }
+    const value = sanitizeForJson(result.value);
+    if (options.quiet) {
+        printJson(value);
+    }
+    else {
+        printJson({ value, trace: options.traceFile ? { file: options.traceFile } : result.trace });
+    }
+    if (options.tracePretty || options.verbose) {
+        console.log(formatTrace(result.trace));
+    }
+    return 0;
+}
+function loadCliProgram(options) {
+    if (!options.file) {
+        throw new Error("Missing AgentScript file");
+    }
+    return loadProgram(options.file);
+}
+function readInput(options) {
+    if (options.input && options.inputFile) {
+        throw new Error("Use either --input or --input-file, not both");
+    }
+    if (options.inputFile) {
+        return parseJsonObjectInput(readFileSync(options.inputFile, "utf8"), "--input-file");
+    }
+    if (options.input) {
+        return parseJsonObjectInput(options.input, "--input");
+    }
+    return {};
+}
+function terminalInputProvider() {
+    if (!inputStream.isTTY || !outputStream.isTTY) {
+        return undefined;
+    }
+    return new TerminalInputProvider();
+}
+class TerminalInputProvider {
+    interface;
+    async read(request) {
+        const answer = await this.reader().question(`${request.path.join(".")}: `);
+        return parseInteractiveInputValue(answer);
+    }
+    reader() {
+        this.interface ??= createInterface({ input: inputStream, output: outputStream });
+        return this.interface;
+    }
+    close() {
+        this.interface?.close();
+    }
+}
+function printUsage(write) {
+    write([
+        "Usage:",
+        "  agentscript <file.as> --input '{\"question\":\"...\"}'",
+        "  agentscript <file.as>",
+        "  agentscript <file.as> --input-file input.json --agent AgentName",
+        "  agentscript <file.as> --input '{}' --quiet",
+        "  agentscript <file.as> --input '{}' --verbose",
+        "  agentscript <file.as> --input '{}' --trace pretty",
+        "  agentscript <file.as> --check",
+        "  agentscript <file.as> --parse",
+        "  agentscript",
+    ].join("\n"));
+}
+function readPackageVersion() {
+    const packagePath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    return typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+const ENTRYPOINT_NAMES = new Set(["agentscript", "agentscript.js", "agentscript.ts"]);
+const isEntrypoint = process.argv[1] ? ENTRYPOINT_NAMES.has(basename(process.argv[1])) : false;
+if (isEntrypoint) {
+    process.exitCode = await main();
+}

package/dist/bin/input.js

@@ -0,0 +1,19 @@
+export function parseJsonObjectInput(source, label) {
+    const value = JSON.parse(source);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return value;
+}
+export function parseInteractiveInputValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return value;
+    }
+}