@rong/agentscript 0.1.0

package/dist/runtime/input.js

@@ -0,0 +1,38 @@
+import { RuntimeError } from "./errors.js";
+import { isObject } from "./guards.js";
+import { sanitizeForJson } from "./json.js";
+import { validateValueAgainstShapeType } from "./shape.js";
+export async function prepareEntryInput(input, entry, inputProvider, trace) {
+    const inputParam = entry.params[0];
+    if (!inputParam?.shape) {
+        return input;
+    }
+    if (!isObject(input)) {
+        throw new RuntimeError("Entry input must be a JSON object", inputParam.range);
+    }
+    await fillShape(input, inputParam.shape, ["input"], inputProvider, trace);
+    return input;
+}
+async function fillShape(target, shape, path, inputProvider, trace) {
+    for (const field of shape.fields) {
+        const fieldPath = [...path, field.name];
+        const value = target[field.name];
+        if (value === undefined || value === null) {
+            if (!inputProvider) {
+                throw new RuntimeError(`Missing input '${fieldPath.join(".")}' and no interactive input provider is available`, field.range);
+            }
+            const filled = await inputProvider.read({ name: field.name, path: fieldPath });
+            validateInputField(filled, field);
+            target[field.name] = filled;
+            trace.push({
+                kind: "input",
+                data: { path: fieldPath.join("."), value: sanitizeForJson(filled) },
+            });
+            continue;
+        }
+        validateInputField(value, field);
+    }
+}
+function validateInputField(value, field) {
+    validateValueAgainstShapeType(value, field.type, field.range, "Input field");
+}

package/dist/runtime/interpreter.js

@@ -0,0 +1,314 @@
+import { readFileSync } from "node:fs";
+import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { formatExpressionSource } from "../ast/format.js";
+import { assertSemanticallyValid } from "../semantic/analyzer.js";
+import { Evaluator } from "./evaluator.js";
+import { RuntimeError } from "./errors.js";
+import { GenerateRuntime } from "./generate.js";
+import { isObject } from "./guards.js";
+import { budgetToJson, sanitizeForJson } from "./json.js";
+import { prepareEntryInput } from "./input.js";
+import { RuntimeScope } from "./scope.js";
+import { assertNever } from "../utils/assert.js";
+import { isTruthy } from "./truth.js";
+import { createDefaultMemoryProvider } from "../providers/memory/index.js";
+import { MockLlmProvider } from "../providers/mock/index.js";
+import { createDefaultToolProvider } from "../providers/tools/index.js";
+const MAX_CALL_DEPTH = 1000;
+export async function executeAgent(program, input, options = {}) {
+    assertSemanticallyValid(program);
+    const interpreter = new Interpreter(program, options);
+    const value = await interpreter.execute(input);
+    return { value, trace: interpreter.trace };
+}
+class Interpreter {
+    program;
+    options;
+    trace = [];
+    llmProvider;
+    inputProvider;
+    toolProvider;
+    memoryProvider;
+    evaluator;
+    entryFunction;
+    agent;
+    currentAgent;
+    agents = new Map();
+    files = new Map();
+    tools = new Map();
+    llms = new Map();
+    memories = new Map();
+    callDepth = 0;
+    constructor(program, options) {
+        this.program = program;
+        this.options = options;
+        this.llmProvider = options.llmProvider ?? new MockLlmProvider();
+        this.inputProvider = options.inputProvider;
+        this.toolProvider = options.toolProvider ?? createDefaultToolProvider(options.workspaceRoot);
+        this.memoryProvider = options.memoryProvider ?? createDefaultMemoryProvider({
+            baseDir: this.programSourceDir(),
+            workspaceRoot: options.workspaceRoot ?? this.programSourceDir(),
+        });
+        const generateRuntime = new GenerateRuntime(this.llmProvider, this.trace, {
+            currentAgent: () => this.currentAgent,
+            evaluate: (expr, scope) => this.evaluator.evaluate(expr, scope),
+            resolveContextUses: (scope) => this.evaluator.resolveContextUses(scope),
+        });
+        this.evaluator = new Evaluator(this.toolProvider, this.memoryProvider, this.trace, generateRuntime, {
+            callAgent: (agentName, functionName, args, range) => this.callAgent(agentName, functionName, args, range),
+            callFunction: (agent, name, args, range) => this.callFunction(agent, name, args, range),
+            requireAgent: (name, range) => this.requireAgent(name, range),
+            resolveMainFunction: (agent) => this.resolveMainFunction(agent),
+        });
+        for (const agent of program.agents) {
+            this.agents.set(agent.name, agent);
+        }
+        this.agent = this.resolveAgent(options.agentName);
+        this.currentAgent = this.agent;
+        this.entryFunction = options.functionName ?? this.resolveMainFunction(this.agent).name;
+        this.registerImports(program);
+    }
+    registerImports(program) {
+        for (const imported of program.imports) {
+            switch (imported.resourceKind) {
+                case "tool":
+                    this.tools.set(imported.name, { __agentScriptResource: "tool", name: imported.name, uri: imported.uri });
+                    break;
+                case "llm":
+                    this.llms.set(imported.name, { __agentScriptResource: "llm", name: imported.name, uri: imported.uri });
+                    break;
+                case "file":
+                    this.files.set(imported.name, this.loadImportedFile(imported.uri));
+                    break;
+                case "memory":
+                    this.memories.set(imported.name, { __agentScriptResource: "memory", name: imported.name, uri: imported.uri });
+                    break;
+            }
+        }
+    }
+    loadImportedFile(uri) {
+        const path = this.resolveImportPath(uri);
+        const content = readFileSync(path, "utf8");
+        if (extname(path).toLowerCase() === ".json") {
+            return JSON.parse(content);
+        }
+        return content;
+    }
+    resolveImportPath(uri) {
+        if (uri.startsWith("file://")) {
+            return new URL(uri).pathname;
+        }
+        if (isAbsolute(uri)) {
+            return uri;
+        }
+        return resolve(this.programSourceDir(), uri);
+    }
+    programSourceDir() {
+        return this.options.sourcePath ? dirname(resolve(this.options.sourcePath)) : process.cwd();
+    }
+    async execute(input) {
+        const entry = this.findFunction(this.agent, this.entryFunction);
+        if (!entry) {
+            throw new RuntimeError(`Unknown function '${this.entryFunction}'`);
+        }
+        const args = entry.params.length === 0 ? [] : [await prepareEntryInput(input, entry, this.inputProvider, this.trace)];
+        return this.callFunction(this.agent, entry.name, args, entry.range);
+    }
+    resolveAgent(agentName) {
+        if (agentName) {
+            const agent = this.program.agents.find((item) => item.name === agentName);
+            if (!agent)
+                throw new RuntimeError(`Unknown agent '${agentName}'`);
+            return agent;
+        }
+        const main = this.program.agents.find((item) => item.isMain);
+        if (main)
+            return main;
+        if (this.program.agents.length !== 1) {
+            throw new RuntimeError("main agent is required when a program contains multiple agents");
+        }
+        return this.program.agents[0];
+    }
+    resolveMainFunction(agent) {
+        const main = agent.functions.find((fn) => fn.isMain);
+        if (main)
+            return main;
+        throw new RuntimeError(`Agent '${agent.name}' has no main func`);
+    }
+    async callFunction(agent, name, args, range) {
+        const fn = this.findFunction(agent, name);
+        if (!fn) {
+            throw new RuntimeError(`Unknown function '${agent.name}.${name}'`, range);
+        }
+        if (args.length !== fn.params.length) {
+            throw new RuntimeError(`Function '${agent.name}.${name}' expects ${fn.params.length} argument(s), got ${args.length}`, fn.range);
+        }
+        if (this.callDepth >= MAX_CALL_DEPTH) {
+            throw new RuntimeError(`Maximum call depth of ${MAX_CALL_DEPTH} exceeded`, range ?? fn.range);
+        }
+        const previousAgent = this.currentAgent;
+        this.currentAgent = agent;
+        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;
+        }
+        finally {
+            this.callDepth -= 1;
+            this.currentAgent = previousAgent;
+        }
+    }
+    async buildFunctionScope(agent, fn, args) {
+        const scope = new RuntimeScope();
+        for (const agentName of this.agents.keys()) {
+            scope.define(agentName, { __agentScriptResource: "agent", name: agentName }, "agent");
+        }
+        for (const [toolName, tool] of this.tools) {
+            scope.define(toolName, tool, "tool");
+        }
+        for (const [llmName, llm] of this.llms) {
+            scope.define(llmName, llm, "llm");
+        }
+        for (const [fileName, file] of this.files) {
+            scope.define(fileName, file, "file");
+        }
+        for (const [memoryName, memory] of this.memories) {
+            scope.define(memoryName, memory, "memory");
+        }
+        for (const func of agent.functions) {
+            scope.define(func.name, { __agentScriptResource: "function", agentName: agent.name, name: func.name }, "function");
+        }
+        for (const config of agent.config) {
+            const configValue = await this.evaluator.evaluateConfig(config, scope);
+            scope.setConfig(config.key, configValue);
+        }
+        for (const [index, param] of fn.params.entries()) {
+            scope.define(param.name, args[index] ?? null, "param");
+        }
+        return scope;
+    }
+    findFunction(agent, name) {
+        return agent.functions.find((fn) => fn.name === name);
+    }
+    async executeBlock(statements, scope) {
+        for (const stmt of statements) {
+            const result = await this.executeStatement(stmt, scope);
+            if (result)
+                return result;
+        }
+        return undefined;
+    }
+    async executeStatement(stmt, scope) {
+        switch (stmt.kind) {
+            case "ConfigStmt":
+                scope.setConfig(stmt.key, await this.evaluator.evaluateConfig(stmt, scope));
+                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) } });
+                return undefined;
+            }
+            case "AssignStmt": {
+                const value = await this.evaluator.evaluate(stmt.value, scope);
+                if (stmt.target.kind === "IdentifierExpr") {
+                    scope.set(stmt.target.name, value);
+                    return undefined;
+                }
+                if (stmt.target.kind === "MemberExpr") {
+                    const object = await this.evaluator.evaluate(stmt.target.object, scope);
+                    if (Array.isArray(object)) {
+                        throw new RuntimeError("Cannot assign a property on a list value", stmt.target.range);
+                    }
+                    if (!isObject(object)) {
+                        throw new RuntimeError("Cannot assign a property on a non-object value", stmt.target.range);
+                    }
+                    object[stmt.target.property] = value;
+                    return undefined;
+                }
+                throw new RuntimeError("Invalid assignment target", stmt.target.range);
+            }
+            case "ExprStmt":
+                await this.evaluator.evaluate(stmt.expr, scope);
+                return undefined;
+            case "IfStmt": {
+                if (isTruthy(await this.evaluator.evaluate(stmt.condition, scope))) {
+                    return this.executeBlock(stmt.thenBody, scope.child());
+                }
+                if (stmt.elseBody) {
+                    return this.executeBlock(stmt.elseBody, scope.child());
+                }
+                return undefined;
+            }
+            case "ForInStmt": {
+                const iterable = await this.evaluator.evaluate(stmt.iterable, scope);
+                if (!Array.isArray(iterable)) {
+                    throw new RuntimeError("for loop requires a list value", stmt.iterable.range);
+                }
+                const iterations = Math.min(stmt.maxIterations, iterable.length);
+                for (let index = 0; index < iterations; index += 1) {
+                    const item = iterable[index];
+                    this.trace.push({
+                        kind: "for",
+                        data: { item: stmt.itemName, index, value: sanitizeForJson(item) }
+                    });
+                    const child = scope.child();
+                    child.define(stmt.itemName, item);
+                    const result = await this.executeBlock(stmt.body, child);
+                    if (result)
+                        return result;
+                }
+                return undefined;
+            }
+            case "LoopUntilStmt": {
+                for (let index = 0; index < stmt.maxIterations; index += 1) {
+                    if (isTruthy(await this.evaluator.evaluate(stmt.condition, scope))) {
+                        return undefined;
+                    }
+                    const result = await this.executeBlock(stmt.body, scope.child());
+                    if (result)
+                        return result;
+                }
+                return undefined;
+            }
+            case "RepeatStmt": {
+                for (let index = 0; index < stmt.maxAttempts; index += 1) {
+                    const result = await this.executeBlock(stmt.body, scope.child());
+                    if (result)
+                        return result;
+                }
+                return undefined;
+            }
+            case "ReturnStmt":
+                return { kind: "return", value: await this.evaluator.evaluate(stmt.value, scope) };
+            default:
+                assertNever(stmt);
+        }
+    }
+    async callAgent(agentName, functionName, args, range) {
+        const traceStart = this.trace.length;
+        const result = await this.callFunction(this.requireAgent(agentName, range), functionName, args, range);
+        const childTrace = this.trace.splice(traceStart);
+        this.trace.push({
+            kind: "agent",
+            data: {
+                agent: agentName,
+                function: functionName,
+                args: sanitizeForJson(args),
+                result: sanitizeForJson(result),
+                trace: childTrace.map((event) => sanitizeForJson(event)),
+            },
+        });
+        return result;
+    }
+    requireAgent(name, range) {
+        const agent = this.agents.get(name);
+        if (!agent)
+            throw new RuntimeError(`Unknown agent '${name}'`, range);
+        return agent;
+    }
+}

package/dist/runtime/json.js

@@ -0,0 +1,59 @@
+import { assertNever } from "../utils/assert.js";
+import { isRuntimeResource } from "./guards.js";
+export function sanitizeForJson(value) {
+    return sanitizeForJsonValue(value, new WeakSet());
+}
+export function runtimeValuesEqual(left, right) {
+    return renderJsonForComparison(left ?? null) === renderJsonForComparison(right ?? null);
+}
+function sanitizeForJsonValue(value, seen) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (isRuntimeResource(value)) {
+        return runtimeResourceToJson(value);
+    }
+    if (seen.has(value)) {
+        return "[Circular]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const result = value.map((item) => sanitizeForJsonValue(item, seen));
+        seen.delete(value);
+        return result;
+    }
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        result[key] = sanitizeForJsonValue(item, seen);
+    }
+    seen.delete(value);
+    return result;
+}
+function renderJsonForComparison(value) {
+    return JSON.stringify(sanitizeForJson(value));
+}
+function runtimeResourceToJson(value) {
+    switch (value.__agentScriptResource) {
+        case "tool":
+            return { tool: value.name, uri: value.uri };
+        case "llm":
+            return { llm: value.name, uri: value.uri };
+        case "function":
+            return { function: value.name, agent: value.agentName };
+        case "agent":
+            return { agent: value.name };
+        case "memory":
+            return { memory: value.name, uri: value.uri };
+        default:
+            assertNever(value);
+    }
+}
+export function budgetToJson(budget) {
+    if (!budget) {
+        return null;
+    }
+    return {
+        amount: budget.amount,
+        unit: budget.unit ?? null,
+    };
+}

package/dist/runtime/loader.js

@@ -0,0 +1,146 @@
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { parse } from "../parser/parser.js";
+export function loadProgram(path) {
+    const entryPath = resolve(path);
+    const state = createLoadState();
+    const program = readProgram(entryPath, state);
+    mergeEntryProgram(program, dirname(entryPath), state);
+    return loadedProgram(program, state);
+}
+export function loadProgramSource(source, options = {}) {
+    const sourcePath = options.sourcePath ? resolve(options.sourcePath) : undefined;
+    const state = createLoadState();
+    const program = parse(source);
+    const baseDir = sourceBaseDir(program, sourcePath);
+    mergeEntryProgram(program, baseDir, state);
+    return loadedProgram(program, state);
+}
+function sourceBaseDir(program, sourcePath) {
+    if (sourcePath) {
+        return dirname(sourcePath);
+    }
+    ensureNoRelativeImports(program);
+    return process.cwd();
+}
+function ensureNoRelativeImports(program) {
+    for (const imported of program.imports) {
+        if (requiresFileResolution(imported) && isRelativeImport(imported.uri)) {
+            throw new Error(`sourcePath is required to resolve relative ${imported.resourceKind} import '${imported.uri}'`);
+        }
+    }
+}
+function createLoadState() {
+    return {
+        agentImportKeys: new Set(),
+        imports: [],
+        importKeys: new Set(),
+        loadingFiles: new Set(),
+        programs: new Map(),
+        agents: [],
+    };
+}
+function loadedProgram(program, state) {
+    return {
+        ...program,
+        imports: state.imports,
+        agents: state.agents,
+    };
+}
+function readProgram(path, state) {
+    const cached = state.programs.get(path);
+    if (cached) {
+        return cached;
+    }
+    const program = parse(readFileSync(path, "utf8"));
+    state.programs.set(path, program);
+    return program;
+}
+function mergeEntryProgram(program, baseDir, state) {
+    mergeImports(program.imports, baseDir, state);
+    state.agents.push(...program.agents);
+}
+function mergeImports(imports, baseDir, state) {
+    for (const imported of imports) {
+        if (imported.resourceKind === "agent") {
+            loadAgentImport(imported, baseDir, state);
+        }
+        else {
+            addImport(normalizeImport(imported, baseDir), state);
+        }
+    }
+}
+function loadAgentImport(imported, baseDir, state) {
+    const path = resolveImportPath(imported.uri, baseDir);
+    const importKey = `${path}#${imported.name}`;
+    if (state.agentImportKeys.has(importKey)) {
+        return;
+    }
+    if (state.loadingFiles.has(path)) {
+        throw new Error(`Circular agent import detected at ${imported.uri}`);
+    }
+    state.agentImportKeys.add(importKey);
+    state.loadingFiles.add(path);
+    try {
+        const program = readProgram(path, state);
+        mergeImports(program.imports, dirname(path), state);
+        const agent = program.agents.find((item) => item.name === imported.name);
+        if (!agent) {
+            throw new Error(`Imported agent '${imported.name}' was not found in ${imported.uri}`);
+        }
+        state.agents.push({
+            ...agent,
+            isMain: false,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load agent import '${imported.name}' from ${path}: ${message}`);
+    }
+    finally {
+        state.loadingFiles.delete(path);
+    }
+}
+function addImport(imported, state) {
+    const key = `${imported.resourceKind}:${imported.name}:${imported.uri}`;
+    if (state.importKeys.has(key)) {
+        return;
+    }
+    state.importKeys.add(key);
+    state.imports.push(imported);
+}
+function normalizeImport(imported, baseDir) {
+    if (imported.resourceKind !== "file" && imported.resourceKind !== "memory") {
+        return imported;
+    }
+    if (imported.resourceKind === "memory" && !imported.uri.startsWith("file://")) {
+        return imported;
+    }
+    const path = resolveImportPath(imported.uri, baseDir);
+    return {
+        ...imported,
+        uri: imported.resourceKind === "memory" ? `file://${path}` : path,
+    };
+}
+function resolveImportPath(uri, baseDir) {
+    if (uri.startsWith("file://")) {
+        const path = decodeURIComponent(uri.slice("file://".length));
+        return isAbsolute(path) ? path : resolve(baseDir, path);
+    }
+    if (isAbsolute(uri)) {
+        return uri;
+    }
+    return resolve(baseDir, uri);
+}
+function isRelativeImport(uri) {
+    return !uri.startsWith("file://") && !isAbsolute(uri) && (uri.startsWith("./") || uri.startsWith("../"));
+}
+const FILE_RESOLUTION_KINDS = new Set(["agent", "file"]);
+function requiresFileResolution(imported) {
+    if (FILE_RESOLUTION_KINDS.has(imported.resourceKind)) {
+        return true;
+    }
+    return (imported.resourceKind === "memory" &&
+        imported.uri.startsWith("file://") &&
+        isRelativeImport(imported.uri.slice("file://".length)));
+}

package/dist/runtime/scope.js

@@ -0,0 +1,47 @@
+import { RuntimeError } from "./errors.js";
+const MUTABLE_BINDING_KINDS = new Set(["local", "param"]);
+export class RuntimeScope {
+    parent;
+    bindings = new Map();
+    config = new Map();
+    uses = [];
+    constructor(parent) {
+        this.parent = parent;
+    }
+    child() {
+        return new RuntimeScope(this);
+    }
+    define(name, value, kind = "local") {
+        this.bindings.set(name, { value, kind });
+    }
+    get(name, range) {
+        const binding = this.resolveBinding(name);
+        if (!binding) {
+            throw new RuntimeError(`Unknown variable '${name}'`, range);
+        }
+        return binding.value;
+    }
+    set(name, value) {
+        const binding = this.resolveBinding(name);
+        if (binding && MUTABLE_BINDING_KINDS.has(binding.kind)) {
+            binding.value = value;
+            return;
+        }
+        this.define(name, value);
+    }
+    addUse(expr, source, budget) {
+        this.uses.push({ expr, source, budget, scope: this });
+    }
+    setConfig(name, value) {
+        this.config.set(name, value);
+    }
+    getConfig(name) {
+        return this.config.get(name) ?? this.parent?.getConfig(name);
+    }
+    visibleUses() {
+        return [...(this.parent?.visibleUses() ?? []), ...this.uses];
+    }
+    resolveBinding(name) {
+        return this.bindings.get(name) ?? this.parent?.resolveBinding(name);
+    }
+}