c64bridge 0.5.0

package/dist/tools/programRunners.js

@@ -0,0 +1,315 @@
+import { AssemblyError } from "../assemblyConverter.js";
+import { defineToolModule } from "./types.js";
+import { objectSchema, stringSchema } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolExecutionError, ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+function extractFailureDetails(details) {
+    if (details === undefined || details === null) {
+        return undefined;
+    }
+    if (typeof details === "object") {
+        return details;
+    }
+    return { value: details };
+}
+function toRecord(details) {
+    if (details === undefined || details === null) {
+        return undefined;
+    }
+    if (typeof details === "object") {
+        return details;
+    }
+    return { value: details };
+}
+const uploadBasicArgsSchema = objectSchema({
+    description: "Arguments for uploading and running a BASIC program.",
+    properties: {
+        program: stringSchema({
+            description: "Commodore BASIC v2 program source to upload and run.",
+            minLength: 1,
+        }),
+    },
+    required: ["program"],
+    additionalProperties: false,
+});
+const uploadAsmArgsSchema = objectSchema({
+    description: "Arguments for uploading and running a 6502/6510 assembly program.",
+    properties: {
+        program: stringSchema({
+            description: "Assembly source that will be assembled to a PRG and executed.",
+            minLength: 1,
+        }),
+    },
+    required: ["program"],
+    additionalProperties: false,
+});
+const prgFileArgsSchema = objectSchema({
+    description: "Arguments for loading or running a PRG that already exists on the Ultimate filesystem.",
+    properties: {
+        path: stringSchema({
+            description: "Absolute or Ultimate filesystem path to the PRG file (e.g. //USB0/demo.prg).",
+            minLength: 1,
+        }),
+    },
+    required: ["path"],
+    additionalProperties: false,
+});
+const crtFileArgsSchema = objectSchema({
+    description: "Arguments for running a CRT image stored on the Ultimate filesystem.",
+    properties: {
+        path: stringSchema({
+            description: "Absolute or Ultimate filesystem path to the CRT file (e.g. //USB0/game.crt).",
+            minLength: 1,
+        }),
+    },
+    required: ["path"],
+    additionalProperties: false,
+});
+export const programRunnersModule = defineToolModule({
+    domain: "programs",
+    summary: "Program uploaders, runners, and compilation workflows for BASIC, assembly, and PRG files.",
+    resources: [
+        "c64://context/bootstrap",
+        "c64://specs/basic",
+        "c64://specs/assembly",
+    ],
+    prompts: ["basic-program", "assembly-program"],
+    defaultTags: ["programs", "execution"],
+    workflowHints: [
+        "Choose BASIC or assembly uploaders based on the language you just generated for the user.",
+        "Prefer PRG or CRT runners when the user supplies an Ultimate filesystem path instead of source text.",
+    ],
+    tools: [
+        {
+            name: "upload_and_run_basic",
+            description: "Upload a BASIC program to the C64 and execute it immediately. Refer to c64://specs/basic for syntax and device I/O.",
+            summary: "Uploads Commodore BASIC v2 source and runs it via Ultimate 64 firmware.",
+            inputSchema: uploadBasicArgsSchema.jsonSchema,
+            relatedResources: ["c64://specs/basic", "c64://context/bootstrap"],
+            relatedPrompts: ["basic-program"],
+            tags: ["basic", "execution"],
+            prerequisites: ["read_screen"],
+            examples: [
+                {
+                    name: "Hello loop",
+                    description: "Print HELLO in a loop",
+                    arguments: { program: "10 PRINT \"HELLO\"\n20 GOTO 10" },
+                },
+            ],
+            workflowHints: [
+                "Invoke right after you generate BASIC source so it runs on the C64 without extra user steps.",
+                "Ensure the program includes line numbers and uppercase keywords before calling the tool.",
+            ],
+            supportedPlatforms: ["c64u", "vice"],
+            async execute(args, ctx) {
+                try {
+                    const parsed = uploadBasicArgsSchema.parse(args);
+                    ctx.logger.info("Uploading BASIC program", { sourceLength: parsed.program.length });
+                    const result = await ctx.client.uploadAndRunBasic(parsed.program);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while running BASIC program", {
+                            details: extractFailureDetails(result.details),
+                        });
+                    }
+                    const base = textResult("BASIC program uploaded and executed successfully.", {
+                        success: true,
+                        details: result.details ?? null,
+                    });
+                    return base;
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "upload_and_run_asm",
+            description: "Assemble 6502/6510 source code, upload the PRG, and run it immediately. See c64://specs/assembly.",
+            summary: "Compiles assembly to a PRG and executes it on the C64 via Ultimate 64 firmware.",
+            inputSchema: uploadAsmArgsSchema.jsonSchema,
+            relatedResources: ["c64://specs/assembly", "c64://context/bootstrap"],
+            relatedPrompts: ["assembly-program"],
+            tags: ["assembly", "execution"],
+            prerequisites: ["read_screen"],
+            examples: [
+                {
+                    name: "Set screen char",
+                    description: "Write 1 to $0400 then RTS",
+                    arguments: { program: ".org $0801\nstart: lda #$01\n sta $0400\n rts" },
+                },
+            ],
+            workflowHints: [
+                "Use when the user requests to run new 6502 code; surface any assembler diagnostics in your reply.",
+                "Mention the entry routine or important addresses after execution so the user can continue debugging.",
+            ],
+            supportedPlatforms: ["c64u", "vice"],
+            async execute(args, ctx) {
+                try {
+                    const parsed = uploadAsmArgsSchema.parse(args);
+                    ctx.logger.info("Uploading assembly program", { sourceLength: parsed.program.length });
+                    const result = await ctx.client.uploadAndRunAsm(parsed.program);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while running assembly program", {
+                            details: extractFailureDetails(result.details),
+                        });
+                    }
+                    return textResult("Assembly program assembled, uploaded, and executed successfully.", {
+                        success: true,
+                        details: result.details ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    if (error instanceof AssemblyError) {
+                        const { file, line } = error.location;
+                        const validationError = new ToolValidationError("Assembly failed", {
+                            details: {
+                                file,
+                                line,
+                                message: error.message,
+                            },
+                            cause: error,
+                        });
+                        return toolErrorResult(validationError);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "load_prg_file",
+            description: "Load a PRG into C64 memory without executing it.",
+            summary: "Instructs the Ultimate firmware to transfer a PRG into memory without RUN.",
+            inputSchema: prgFileArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap"],
+            tags: ["programs", "file"],
+            prerequisites: ["drives_list"],
+            examples: [
+                {
+                    name: "Load PRG from USB",
+                    description: "Load without running",
+                    arguments: { path: "//USB0/demo.prg" },
+                },
+            ],
+            workflowHints: [
+                "Stage PRG files without running when the user wants to inspect memory first.",
+                "Confirm the Ultimate filesystem path (e.g. //USB0/demo.prg) is accessible before invoking.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = prgFileArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Loading PRG file", { path: parsed.path });
+                    const result = await ctx.client.loadPrgFile(parsed.path);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while loading PRG", {
+                            details: extractFailureDetails(result.details),
+                        });
+                    }
+                    return textResult(`PRG ${parsed.path} loaded into memory.`, {
+                        success: true,
+                        path: parsed.path,
+                        details: toRecord(result.details) ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "run_prg_file",
+            description: "Run a PRG located on the Ultimate filesystem without uploading source.",
+            summary: "Loads and executes a PRG file residing on attached storage.",
+            inputSchema: prgFileArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap"],
+            tags: ["programs", "execution", "file"],
+            workflowHints: [
+                "Call when the user provides a PRG path and expects immediate execution without compiling.",
+                "Mention that firmware issues a RUN so the user knows the machine state changed.",
+            ],
+            supportedPlatforms: ["c64u", "vice"],
+            prerequisites: ["drives_list"],
+            examples: [
+                {
+                    name: "Run PRG from USB",
+                    description: "Load and RUN",
+                    arguments: { path: "//USB0/demo.prg" },
+                },
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = prgFileArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Running PRG file", { path: parsed.path });
+                    const result = await ctx.client.runPrgFile(parsed.path);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while running PRG", {
+                            details: extractFailureDetails(result.details),
+                        });
+                    }
+                    return textResult(`PRG ${parsed.path} loaded and executed.`, {
+                        success: true,
+                        path: parsed.path,
+                        details: toRecord(result.details) ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "run_crt_file",
+            description: "Run a cartridge image stored on the Ultimate filesystem.",
+            summary: "Mounts and autostarts the specified CRT file through the firmware.",
+            inputSchema: crtFileArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap"],
+            tags: ["programs", "cartridge"],
+            workflowHints: [
+                "Use for cartridge images and remind the user that the machine will reset into the CRT.",
+                "Suggest capturing the screen afterwards if they need to verify the cartridge booted.",
+            ],
+            prerequisites: ["drives_list"],
+            examples: [
+                {
+                    name: "Start CRT",
+                    description: "Mount and run game.crt",
+                    arguments: { path: "//USB0/game.crt" },
+                },
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = crtFileArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Running CRT file", { path: parsed.path });
+                    const result = await ctx.client.runCrtFile(parsed.path);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while running CRT", {
+                            details: extractFailureDetails(result.details),
+                        });
+                    }
+                    return textResult(`CRT ${parsed.path} mounted and started.`, {
+                        success: true,
+                        path: parsed.path,
+                        details: toRecord(result.details) ?? null,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});

package/dist/tools/rag.js

@@ -0,0 +1,153 @@
+import { listKnowledgeResources } from "../rag/knowledgeIndex.js";
+import { defineToolModule } from "./types.js";
+import { objectSchema, optionalSchema, stringSchema, numberSchema } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+const ragRetrieveArgsSchema = objectSchema({
+    description: "Retrieve domain-specific references from the local C64 knowledge base using embeddings.",
+    properties: {
+        q: stringSchema({
+            description: "Natural-language query describing the desired BASIC or assembly guidance.",
+            minLength: 3,
+        }),
+        k: optionalSchema(numberSchema({
+            description: "Maximum number of references to return (1-12).",
+            integer: true,
+            minimum: 1,
+            maximum: 12,
+            default: 3,
+        })),
+    },
+    required: ["q"],
+    additionalProperties: false,
+});
+function createRagTool(language, options) {
+    const primaryResourceUris = language === "basic"
+        ? ["c64://specs/basic", "c64://context/bootstrap"]
+        : ["c64://specs/assembly", "c64://context/bootstrap"];
+    return {
+        name: language === "basic" ? "rag_retrieve_basic" : "rag_retrieve_asm",
+        description: language === "basic"
+            ? "Retrieve BASIC references from local knowledge. See c64://specs/basic before coding."
+            : "Retrieve 6502/6510 assembly references from local knowledge. See c64://specs/assembly.",
+        summary: options.summary,
+        inputSchema: ragRetrieveArgsSchema.jsonSchema,
+        relatedResources: language === "basic"
+            ? ["c64://specs/basic"]
+            : ["c64://specs/assembly"],
+        relatedPrompts: language === "basic"
+            ? ["basic-program"]
+            : ["assembly-program"],
+        tags: options.tags,
+        prerequisites: [],
+        examples: [
+            {
+                name: language === "basic" ? "BASIC PRINT" : "Raster IRQ",
+                description: language === "basic" ? "Find PRINT and device usage" : "Find stable raster IRQ snippet",
+                arguments: language === "basic"
+                    ? { q: "PRINT to device 4 form feed", k: 3 }
+                    : { q: "stable raster irq acknowledge d019", k: 3 },
+            },
+        ],
+        workflowHints: language === "basic"
+            ? [
+                "Use when the user needs BASIC examples or syntax reminders before coding.",
+                "Summarise key references so the user knows where to look next.",
+            ]
+            : [
+                "Call for assembly patterns, addressing tricks, or hardware explanations before writing code.",
+                "Highlight registers or memory addresses found in the returned references.",
+            ],
+        async execute(args, ctx) {
+            try {
+                const parsed = ragRetrieveArgsSchema.parse(args ?? {});
+                const limit = parsed.k ?? 3;
+                ctx.logger.debug("Retrieving RAG references", {
+                    language,
+                    queryLength: parsed.q.length,
+                    limit,
+                });
+                let refs;
+                try {
+                    refs = await ctx.rag.retrieve(parsed.q, limit, language);
+                }
+                catch (error) {
+                    throw new ToolExecutionError("RAG retrieval failed", { cause: error });
+                }
+                const resources = listKnowledgeResources();
+                const primaryResources = primaryResourceUris
+                    .map((uri) => resources.find((entry) => entry.uri === uri))
+                    .filter((entry) => Boolean(entry));
+                const ragCount = refs.length;
+                const primaryLines = primaryResources.length
+                    ? primaryResources.map((entry) => `- ${entry.name} (${entry.uri}) — ${entry.metadata.summary}`)
+                    : ["- No curated resources found."];
+                const ragLines = ragCount
+                    ? refs.map((ref, index) => `${index + 1}. ${ref}`)
+                    : ["No supplemental RAG references were found."];
+                const text = [
+                    "Primary knowledge resources (consult these first):",
+                    ...primaryLines,
+                    "",
+                    "Supplemental RAG references:",
+                    ...ragLines,
+                ].join("\n");
+                const base = textResult(text, {
+                    success: true,
+                    language,
+                    limit,
+                    queryLength: parsed.q.length,
+                    count: ragCount,
+                });
+                return {
+                    ...base,
+                    structuredContent: {
+                        type: "json",
+                        data: {
+                            primaryResources: primaryResources.map((entry) => ({
+                                uri: entry.uri,
+                                name: entry.name,
+                                summary: entry.metadata.summary,
+                            })),
+                            refs,
+                        },
+                    },
+                };
+            }
+            catch (error) {
+                if (error instanceof ToolError) {
+                    return toolErrorResult(error);
+                }
+                return unknownErrorResult(error);
+            }
+        },
+    };
+}
+export const ragModule = defineToolModule({
+    domain: "rag",
+    summary: "Retrieval-augmented generation helpers for BASIC and assembly examples.",
+    resources: [
+        "c64://specs/basic",
+        "c64://specs/assembly",
+        "c64://docs/index",
+    ],
+    prompts: ["basic-program", "assembly-program"],
+    defaultTags: ["rag", "search"],
+    supportedPlatforms: ["c64u", "vice"],
+    workflowHints: [
+        "Call RAG tools when the user needs references or examples before generating new code.",
+        "Summarise the number of refs returned and suggest follow-up actions like reading specific docs.",
+    ],
+    tools: [
+        createRagTool("basic", {
+            description: "Retrieve BASIC snippets, guidance, and discussion relevant to the provided query.",
+            summary: "Returns BASIC-focused references from the local knowledge base.",
+            tags: ["basic"],
+        }),
+        createRagTool("asm", {
+            description: "Retrieve 6502/6510 assembly routines and references relevant to the provided query.",
+            summary: "Returns assembly-focused references from the local knowledge base.",
+            tags: ["asm"],
+        }),
+    ],
+});

package/dist/tools/registry.js

@@ -0,0 +1,58 @@
+import { programRunnersModule } from "./programRunners.js";
+import { memoryModule } from "./memory.js";
+import { audioModule } from "./audio.js";
+import { machineControlModule } from "./machineControl.js";
+import { storageModule } from "./storage.js";
+import { graphicsModule } from "./graphics.js";
+import { printerModule } from "./printer.js";
+import { ragModule } from "./rag.js";
+import { developerModule } from "./developer.js";
+import { streamingModule } from "./streaming.js";
+import { getPlatformStatus, setPlatform } from "../platform.js";
+const toolModules = [
+    programRunnersModule,
+    memoryModule,
+    audioModule,
+    machineControlModule,
+    storageModule,
+    graphicsModule,
+    printerModule,
+    ragModule,
+    developerModule,
+    streamingModule,
+];
+const toolMap = new Map();
+for (const module of toolModules) {
+    for (const descriptor of module.describeTools()) {
+        if (toolMap.has(descriptor.name)) {
+            throw new Error(`Duplicate tool name detected while registering modules: ${descriptor.name}`);
+        }
+        toolMap.set(descriptor.name, { module, descriptor });
+    }
+}
+export const toolRegistry = {
+    list() {
+        return Array.from(toolMap.values(), (entry) => entry.descriptor);
+    },
+    async invoke(name, args, ctx) {
+        const enrichedCtx = {
+            ...ctx,
+            platform: ctx.platform ?? getPlatformStatus(),
+            setPlatform: ctx.setPlatform ?? setPlatform,
+        };
+        const entry = toolMap.get(name);
+        if (!entry) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return entry.module.invoke(name, args, enrichedCtx);
+    },
+};
+export function describeToolModules() {
+    return toolModules.map((module) => ({
+        domain: module.domain,
+        summary: module.summary,
+        defaultTags: module.defaultTags,
+        workflowHints: module.workflowHints ?? [],
+        tools: module.describeTools(),
+    }));
+}

package/dist/tools/responses.js

@@ -0,0 +1,36 @@
+export function textResult(text, metadata) {
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        metadata,
+    };
+}
+export function jsonResult(data, metadata) {
+    const text = typeof data === "string"
+        ? data
+        : (() => {
+            try {
+                return JSON.stringify(data, null, 2);
+            }
+            catch {
+                return String(data);
+            }
+        })();
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+        structuredContent: {
+            type: "json",
+            data,
+        },
+        metadata,
+    };
+}