@rong/agentscript 0.1.0

package/dist/runtime/context.js

@@ -0,0 +1,160 @@
+import { budgetToJson, sanitizeForJson } from "./json.js";
+export function buildContext(input) {
+    const context = input.uses.map((item, index) => buildContextItem(item, index));
+    const instruction = sanitizeForJson(input.instruction);
+    const instructionText = renderJson(instruction);
+    const system = buildSystemPrompt(input.agentName, input.identity);
+    const returnSchema = shapeToSchema(input.returnShape);
+    return {
+        agentName: input.agentName,
+        model: input.model,
+        identity: input.identity,
+        system,
+        context,
+        instruction,
+        instructionText,
+        returnSchema,
+        budget: input.budget,
+        finalUserMessage: buildFinalUserMessage(context, instructionText, returnSchema),
+    };
+}
+export function shapeToSchema(shape) {
+    const properties = {};
+    const required = [];
+    for (const field of shape.fields) {
+        properties[field.name] = shapeTypeToSchema(field.type);
+        required.push(field.name);
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+const SHAPE_TYPE_TO_JSON_SCHEMA = {
+    string: { type: "string" },
+    number: { type: "number" },
+    boolean: { type: "boolean" },
+    json: {},
+    list: { type: "array" },
+};
+function shapeTypeToSchema(type) {
+    if (type.kind === "ListShapeType") {
+        return { type: "array", items: shapeTypeToSchema(type.itemType) };
+    }
+    return SHAPE_TYPE_TO_JSON_SCHEMA[type.name] ?? {};
+}
+function buildContextItem(item, index) {
+    const value = sanitizeForJson(item.value);
+    const clipped = clipJson(value, item.budget);
+    return {
+        index,
+        source: item.source,
+        value: clipped.value,
+        text: clipped.text,
+        budget: item.budget,
+        clipped: clipped.clipped,
+        originalSize: clipped.originalSize,
+        clippedSize: clipped.clippedSize,
+    };
+}
+function buildSystemPrompt(agentName, identity) {
+    const lines = [`You are ${agentName}.`];
+    for (const [key, value] of Object.entries(identity)) {
+        lines.push(`${key}: ${renderJson(value)}`);
+    }
+    return lines.join("\n");
+}
+function buildFinalUserMessage(context, instructionText, returnSchema) {
+    const sections = [];
+    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}`);
+        }
+    }
+    sections.push("Instruction:", instructionText);
+    sections.push("Return JSON matching this schema:", renderJson(returnSchema));
+    return sections.join("\n");
+}
+function renderJson(value) {
+    return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+function clipJson(value, budget) {
+    const maxChars = budgetToCharLimit(budget);
+    const text = renderJson(value);
+    if (!maxChars || text.length <= maxChars) {
+        return { value, text, clipped: false, originalSize: text.length, clippedSize: text.length };
+    }
+    const clippedValue = clipValueToBudget(value, maxChars);
+    const clippedText = renderJson(clippedValue);
+    return {
+        value: clippedValue,
+        text: clippedText,
+        clipped: clippedText !== text,
+        originalSize: text.length,
+        clippedSize: clippedText.length,
+    };
+}
+function clipValueToBudget(value, maxChars) {
+    if (typeof value === "string")
+        return value.slice(0, maxChars);
+    if (Array.isArray(value))
+        return clipArrayToBudget(value, maxChars);
+    if (value && typeof value === "object")
+        return clipObjectToBudget(value, maxChars);
+    return value;
+}
+function clipArrayToBudget(value, maxChars) {
+    const end = findLargestPrefix(value.length, (count) => renderJson(value.slice(0, count)).length <= maxChars);
+    return value.slice(0, end);
+}
+function clipObjectToBudget(value, maxChars) {
+    const entries = Object.entries(value);
+    const end = findLargestPrefix(entries.length, (count) => renderJson(Object.fromEntries(entries.slice(0, count))).length <= maxChars);
+    return Object.fromEntries(entries.slice(0, end));
+}
+function findLargestPrefix(length, fits) {
+    let low = 0;
+    let high = length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (fits(mid)) {
+            low = mid;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    return low;
+}
+function budgetToCharLimit(budget) {
+    if (!budget)
+        return undefined;
+    const amount = budget.unit === "k" ? budget.amount * 1000 : budget.amount;
+    return Math.floor(amount);
+}
+export function builtContextToJson(context) {
+    return {
+        agentName: context.agentName,
+        model: context.model ? { name: context.model.name, uri: context.model.uri } : null,
+        identity: context.identity,
+        system: context.system,
+        context: context.context.map((item) => ({
+            index: item.index,
+            source: item.source ?? null,
+            value: item.value,
+            text: item.text,
+            budget: budgetToJson(item.budget),
+            clipped: item.clipped,
+            originalSize: item.originalSize,
+            clippedSize: item.clippedSize,
+        })),
+        instruction: context.instruction,
+        returnSchema: context.returnSchema,
+        budget: budgetToJson(context.budget),
+        finalUserMessage: context.finalUserMessage,
+    };
+}

package/dist/runtime/errors.js

@@ -0,0 +1,14 @@
+export class RuntimeError extends Error {
+    range;
+    constructor(message, range) {
+        super(formatRuntimeMessage(message, range));
+        this.range = range;
+        this.name = "RuntimeError";
+    }
+}
+function formatRuntimeMessage(message, range) {
+    if (!range) {
+        return message;
+    }
+    return `${message} at ${range.start.line}:${range.start.column}`;
+}

package/dist/runtime/evaluator.js

@@ -0,0 +1,276 @@
+import { assertNever } from "../utils/assert.js";
+import { RuntimeError } from "./errors.js";
+import { isAgentBinding, isFunctionBinding, isLlmBinding, isMemoryBinding, isObject, isToolBinding, } from "./guards.js";
+import { runtimeValuesEqual, sanitizeForJson } from "./json.js";
+import { uriScheme } from "./uri.js";
+import { isTruthy } from "./truth.js";
+export class Evaluator {
+    toolProvider;
+    memoryProvider;
+    trace;
+    generateRuntime;
+    host;
+    constructor(toolProvider, memoryProvider, trace, generateRuntime, host) {
+        this.toolProvider = toolProvider;
+        this.memoryProvider = memoryProvider;
+        this.trace = trace;
+        this.generateRuntime = generateRuntime;
+        this.host = host;
+    }
+    async evaluateConfig(config, scope) {
+        switch (config.key) {
+            case "model": {
+                const value = await this.evaluate(config.value, scope);
+                if (!isLlmBinding(value)) {
+                    throw new RuntimeError("model must reference an imported llm", config.value.range);
+                }
+                return value;
+            }
+            case "role":
+            case "description": {
+                const value = await this.evaluate(config.value, scope);
+                if (typeof value !== "string") {
+                    throw new RuntimeError(`${config.key} must be a string`, config.value.range);
+                }
+                return value;
+            }
+        }
+    }
+    async evaluate(expr, scope) {
+        switch (expr.kind) {
+            case "IdentifierExpr":
+                return scope.get(expr.name, expr.range);
+            case "StringExpr":
+                return expr.value;
+            case "NumberExpr":
+                return expr.value;
+            case "BooleanExpr":
+                return expr.value;
+            case "NullExpr":
+                return null;
+            case "ListExpr":
+                return this.evaluateAll(expr.items, scope);
+            case "ObjectExpr": {
+                const result = {};
+                for (const property of expr.properties) {
+                    result[property.key] = await this.evaluate(property.value, scope);
+                }
+                return result;
+            }
+            case "ShapeObjectExpr":
+                throw new RuntimeError("Shape object cannot be evaluated as a runtime value", expr.range);
+            case "MemberExpr":
+                return this.evaluateMember(expr, scope);
+            case "IndexExpr":
+                return this.evaluateIndex(expr, scope);
+            case "UnaryExpr":
+                return !isTruthy(await this.evaluate(expr.value, scope));
+            case "BinaryExpr":
+                return this.evaluateBinary(expr, scope);
+            case "CallExpr":
+                return this.evaluateCall(expr, scope);
+            case "GenerateExpr":
+                return this.generateRuntime.evaluateGenerate(expr, scope);
+            default:
+                assertNever(expr);
+        }
+    }
+    async resolveContextUses(scope) {
+        const uses = [];
+        for (const item of scope.visibleUses()) {
+            uses.push({
+                source: item.source,
+                value: await this.evaluate(item.expr, item.scope),
+                budget: item.budget,
+            });
+        }
+        return uses;
+    }
+    async evaluateBinary(expr, scope) {
+        switch (expr.operator) {
+            case "and":
+                return isTruthy(await this.evaluate(expr.left, scope)) && isTruthy(await this.evaluate(expr.right, scope));
+            case "or":
+                return isTruthy(await this.evaluate(expr.left, scope)) || isTruthy(await this.evaluate(expr.right, scope));
+            case "==":
+                return this.valuesEqual(await this.evaluate(expr.left, scope), await this.evaluate(expr.right, scope));
+            case "!=":
+                return !this.valuesEqual(await this.evaluate(expr.left, scope), await this.evaluate(expr.right, scope));
+        }
+    }
+    valuesEqual(left, right) {
+        return runtimeValuesEqual(left, right);
+    }
+    async evaluateMember(expr, scope) {
+        const object = await this.evaluate(expr.object, scope);
+        return this.readMember(object, expr.property, expr.range);
+    }
+    async evaluateIndex(expr, scope) {
+        const object = await this.evaluate(expr.object, scope);
+        const index = await this.evaluate(expr.index, scope);
+        if (!Array.isArray(object)) {
+            throw new RuntimeError("Index access requires a list value", expr.object.range);
+        }
+        if (typeof index !== "number" || !Number.isInteger(index) || index < 0) {
+            throw new RuntimeError("List index must be a non-negative integer", expr.index.range);
+        }
+        if (index >= object.length) {
+            throw new RuntimeError(`List index ${index} is out of range`, expr.index.range);
+        }
+        return object[index];
+    }
+    readMember(object, property, range) {
+        if (Array.isArray(object)) {
+            if (property === "summary") {
+                return object.map((item) => sanitizeForJson(item));
+            }
+            if (property === "length") {
+                return object.length;
+            }
+            throw new RuntimeError(`Unknown list property '${property}'`, range);
+        }
+        if (isObject(object)) {
+            if (!(property in object)) {
+                throw new RuntimeError(`Unknown object property '${property}'`, range);
+            }
+            return object[property];
+        }
+        if (isToolBinding(object))
+            return { tool: object.name, method: property };
+        if (isMemoryBinding(object))
+            return { memory: object.name, method: property };
+        throw new RuntimeError(`Cannot read property '${property}'`, range);
+    }
+    async evaluateCall(expr, scope) {
+        if (expr.callee.kind === "IdentifierExpr") {
+            const args = await this.evaluateAll(expr.args, scope);
+            const callee = scope.get(expr.callee.name, expr.callee.range);
+            if (isFunctionBinding(callee)) {
+                return this.host.callFunction(this.host.requireAgent(callee.agentName), callee.name, args, expr.range);
+            }
+            if (isAgentBinding(callee)) {
+                const agent = this.host.requireAgent(callee.name, expr.range);
+                return this.host.callAgent(callee.name, this.host.resolveMainFunction(agent).name, args, expr.range);
+            }
+            throw new RuntimeError(`'${expr.callee.name}' is not callable`, expr.callee.range);
+        }
+        if (expr.callee.kind === "MemberExpr") {
+            return this.evaluateMemberCall(expr.callee, expr.args, scope);
+        }
+        throw new RuntimeError("Unsupported call expression", expr.range);
+    }
+    async evaluateMemberCall(callee, argsExpr, scope) {
+        const object = await this.evaluate(callee.object, scope);
+        const args = await this.evaluateAll(argsExpr, scope);
+        if (isAgentBinding(object)) {
+            return this.host.callAgent(object.name, callee.property, args, callee.range);
+        }
+        if (isToolBinding(object)) {
+            return this.evaluateToolCall(object, callee, args);
+        }
+        if (isMemoryBinding(object)) {
+            return this.evaluateMemoryCall(object, callee, args);
+        }
+        if (Array.isArray(object) && callee.property === "add") {
+            if (args.length !== 1) {
+                throw new RuntimeError("list.add expects exactly one argument", callee.range);
+            }
+            object.push(args[0]);
+            return object;
+        }
+        throw new RuntimeError(`Unsupported member call '${callee.property}'`, callee.range);
+    }
+    async evaluateToolCall(object, callee, args) {
+        const request = {
+            toolName: object.name,
+            uri: object.uri,
+            method: callee.property,
+            args,
+        };
+        let result;
+        try {
+            result = await this.toolProvider.call(request);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new RuntimeError(`Tool ${object.name}.${callee.property} (${object.uri}) failed: ${message}`, callee.range);
+        }
+        this.trace.push({
+            kind: "tool",
+            data: {
+                tool: object.name,
+                method: callee.property,
+                scheme: uriScheme(object.uri),
+                uri: object.uri,
+                args: sanitizeForJson(args),
+                result: sanitizeForJson(result),
+                effects: this.readEffects(result),
+            },
+        });
+        return result;
+    }
+    async evaluateMemoryCall(object, callee, args) {
+        if (args.length !== 1) {
+            throw new RuntimeError(`memory.${callee.property} expects exactly one argument`, callee.range);
+        }
+        let result;
+        try {
+            if (callee.property === "add") {
+                result = await this.memoryProvider.add({
+                    memoryName: object.name,
+                    uri: object.uri,
+                    record: args[0],
+                });
+            }
+            else if (callee.property === "query") {
+                result = await this.memoryProvider.query({
+                    memoryName: object.name,
+                    uri: object.uri,
+                    query: args[0],
+                });
+            }
+            else {
+                throw new RuntimeError(`Unknown memory method '${callee.property}'`, callee.range);
+            }
+        }
+        catch (error) {
+            if (error instanceof RuntimeError) {
+                throw error.range ? error : new RuntimeError(error.message, callee.range);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new RuntimeError(`Memory ${object.name}.${callee.property} (${object.uri}) failed: ${message}`, callee.range);
+        }
+        const traceData = {
+            memory: object.name,
+            operation: callee.property,
+            uri: object.uri,
+            args: sanitizeForJson(args[0]),
+            result: sanitizeForJson(result),
+            count: Array.isArray(result) ? result.length : null,
+        };
+        if (callee.property === "add" && isObject(result)) {
+            Object.assign(traceData, {
+                id: typeof result.id === "string" ? result.id : null,
+                record: sanitizeForJson(result.record),
+            });
+        }
+        this.trace.push({
+            kind: "memory",
+            data: traceData,
+        });
+        return result;
+    }
+    async evaluateAll(exprs, scope) {
+        const values = [];
+        for (const expr of exprs) {
+            values.push(await this.evaluate(expr, scope));
+        }
+        return values;
+    }
+    readEffects(value) {
+        if (isObject(value) && Array.isArray(value.effects)) {
+            return sanitizeForJson(value.effects);
+        }
+        return null;
+    }
+}

package/dist/runtime/generate.js

@@ -0,0 +1,175 @@
+import { buildContext, builtContextToJson } from "./context.js";
+import { RuntimeError } from "./errors.js";
+import { isLlmBinding, isObject } from "./guards.js";
+import { budgetToJson, sanitizeForJson } from "./json.js";
+import { coerceValueToShape, validateValueAgainstShape } from "./shape.js";
+export class GenerateRuntime {
+    llmProvider;
+    trace;
+    host;
+    constructor(llmProvider, trace, host) {
+        this.llmProvider = llmProvider;
+        this.trace = trace;
+        this.host = host;
+    }
+    async evaluateGenerate(expr, scope) {
+        const options = await this.parseOptions(expr, scope);
+        const context = await this.host.resolveContextUses(scope);
+        const agent = this.host.currentAgent();
+        const model = this.requireModel(scope, expr);
+        const identity = this.buildIdentity(scope, expr);
+        let repair;
+        let lastError;
+        for (let attempt = 1; attempt <= options.attempts; attempt += 1) {
+            const instruction = repair ? appendRepair(options.input, repair) : options.input;
+            const builtContext = buildContext({
+                agentName: agent.name,
+                model,
+                identity,
+                instruction,
+                returnShape: expr.returnShape,
+                uses: context,
+                budget: options.limit,
+            });
+            if (options.debug) {
+                writeDebugPrompt(agent.name, attempt, builtContext);
+            }
+            let rawResult;
+            try {
+                rawResult = await this.llmProvider.generate({
+                    agentName: agent.name,
+                    model,
+                    identity,
+                    instruction,
+                    returnShape: expr.returnShape,
+                    context,
+                    builtContext,
+                    budget: options.limit,
+                });
+            }
+            catch (error) {
+                if (attempt >= options.attempts || !isRepairableGenerateError(error)) {
+                    throw withGenerateRange(error, expr.range);
+                }
+                lastError = error;
+                repair = {
+                    error: errorMessage(error)
+                };
+                continue;
+            }
+            try {
+                const result = coerceValueToShape(rawResult, expr.returnShape);
+                validateValueAgainstShape(result, expr.returnShape, expr.range);
+                this.trace.push({
+                    kind: "generate",
+                    data: {
+                        instruction: sanitizeForJson(options.input),
+                        attempts: attempt,
+                        budget: budgetToJson(options.limit),
+                        debug: options.debug,
+                        context: builtContextToJson(builtContext),
+                        result: sanitizeForJson(result),
+                    },
+                });
+                return result;
+            }
+            catch (error) {
+                if (attempt >= options.attempts) {
+                    throw withGenerateRange(error, expr.range);
+                }
+                lastError = error;
+                repair = {
+                    output: rawResult,
+                    error: errorMessage(error),
+                };
+            }
+        }
+        throw lastError instanceof Error ? lastError : new RuntimeError("generate failed", expr.range);
+    }
+    async parseOptions(expr, scope) {
+        if (!expr.options.input) {
+            throw new RuntimeError("generate object argument requires an input field", expr.options.range);
+        }
+        const attempts = expr.options.attempts?.value ?? 1;
+        if (!Number.isInteger(attempts) || attempts <= 0) {
+            throw new RuntimeError("generate attempts must be a positive integer", expr.options.attempts?.range ?? expr.options.range);
+        }
+        return {
+            input: await this.host.evaluate(expr.options.input, scope),
+            attempts,
+            limit: expr.options.limit,
+            debug: expr.options.debug?.value ?? false,
+        };
+    }
+    requireModel(scope, expr) {
+        const model = scope.getConfig("model");
+        if (model === undefined || !isLlmBinding(model)) {
+            throw new RuntimeError("generate requires model in the current scope", expr.range);
+        }
+        return model;
+    }
+    buildIdentity(scope, expr) {
+        const role = scope.getConfig("role");
+        const description = scope.getConfig("description");
+        if (typeof role !== "string") {
+            throw new RuntimeError("generate requires role in the current scope", expr.range);
+        }
+        if (typeof description !== "string") {
+            throw new RuntimeError("generate requires description in the current scope", expr.range);
+        }
+        return {
+            role,
+            description,
+        };
+    }
+}
+function appendRepair(input, repair) {
+    const message = [
+        "Previous generation failed.",
+        repair.output === undefined
+            ? undefined
+            : `Previous output:\n${JSON.stringify(sanitizeForJson(repair.output), null, 2)}`,
+        `Error:\n${repair.error}`,
+        "Return corrected JSON matching the requested schema only.",
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    if (typeof input === "string") {
+        return `${input}\n\n${message}`;
+    }
+    if (isObject(input)) {
+        return {
+            ...input,
+            repair: message,
+        };
+    }
+    return {
+        input,
+        repair: message,
+    };
+}
+function isRepairableGenerateError(error) {
+    return error instanceof RuntimeError && /LLM provider did not return JSON/.test(error.message);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function withGenerateRange(error, range) {
+    if (error instanceof RuntimeError) {
+        return new RuntimeError(error.message, error.range ?? range);
+    }
+    return new RuntimeError(errorMessage(error), range);
+}
+function writeDebugPrompt(agentName, attempt, builtContext) {
+    const parts = [
+        `--- AgentScript generate debug: ${agentName} attempt ${attempt} ---`,
+        "System:",
+        builtContext.system,
+        "Final user message:",
+        builtContext.finalUserMessage,
+        "Return schema:",
+        JSON.stringify(builtContext.returnSchema, null, 2),
+        "--- end AgentScript generate debug ---",
+    ];
+    console.error(parts.join("\n"));
+}

package/dist/runtime/guards.js

@@ -0,0 +1,39 @@
+export function isToolBinding(value) {
+    return isResourceBinding(value, "tool");
+}
+export function isLlmBinding(value) {
+    return isResourceBinding(value, "llm");
+}
+export function isFunctionBinding(value) {
+    return isResourceBinding(value, "function");
+}
+export function isAgentBinding(value) {
+    return isResourceBinding(value, "agent");
+}
+export function isMemoryBinding(value) {
+    return isResourceBinding(value, "memory");
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !isRuntimeResource(value);
+}
+export function isRuntimeResource(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && "__agentScriptResource" in value;
+}
+const RESOURCE_KINDS_WITH_URI = new Set(["tool", "llm", "memory"]);
+function isResourceBinding(value, resourceKind) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        !("__agentScriptResource" in value) ||
+        value.__agentScriptResource !== resourceKind) {
+        return false;
+    }
+    const binding = value;
+    if (RESOURCE_KINDS_WITH_URI.has(resourceKind)) {
+        return typeof binding.name === "string" && typeof binding.uri === "string";
+    }
+    if (resourceKind === "function") {
+        return typeof binding.name === "string" && typeof binding.agentName === "string";
+    }
+    return typeof binding.name === "string";
+}