c64bridge 1.0.6 → 1.1.0

package/dist/tools/registry/memory.js

@@ -1,5 +1,5 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
-import { memoryModule, memoryOperationHandlers as groupedMemoryHandlers, disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, } from "../memory.js";
+import { memoryModule, memoryOperationHandlers as groupedMemoryHandlers, listBasicArgsSchema, disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, } from "../memory.js";
 import { metaModule } from "../meta/index.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
 const memoryDescriptorIndex = buildDescriptorIndex(memoryModule);
@@ -25,6 +25,11 @@ const memoryOperations = [
         schema: extendSchemaWithOp("wait_for_text", ensureDescriptor(metaDescriptorIndex, "wait_for_screen_text").inputSchema, { description: "Poll the screen until a substring or regex appears, or timeout elapses." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "wait_for_screen_text", rawArgs, ctx),
     },
+    {
+        op: "list_basic",
+        schema: extendSchemaWithOp("list_basic", listBasicArgsSchema.jsonSchema, { description: "List the BASIC program in memory as text: reads the $2B-$2E pointers, walks the line links and detokenises. Works on C64U/U64, U2-family hardware, and VICE." }),
+        handler: groupedMemoryHandlers.list_basic,
+    },
     {
         op: "disassemble",
         schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE." }),
@@ -77,6 +82,11 @@ export const memoryModuleGroup = defineToolModule({
                 description: "Memory operations available via the c64_memory tool.",
                 variants: memoryOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                read: "read", write: "write", read_screen: "read", wait_for_text: "read", list_basic: "read", disassemble: "read",
+                copy_memory: "write", fill_memory: "write", search_memory: "read", compare_memory: "read",
+                save_memory: "write",
+            },
             tags: ["memory", "screen", "grouped"],
             examples: [
                 {

package/dist/tools/registry/platform.js

@@ -44,6 +44,7 @@ function describeTargetPlatform(target) {
     return {
         availableTools: info.tools,
         unavailableTools: info.unsupported_tools,
+        unavailableOperations: info.unsupported_operations,
     };
 }
 const selectBackendSchema = operationSchema("select", {
@@ -77,7 +78,7 @@ const platformOperationHandlers = {
         cancelGeneratedSidPlayback(); // A backend switch is the documented cue to stop it rather than let it keep playing on the old backend.
         ctx.client.switchBackend(backend);
         ctx.setPlatform(backend);
-        const { availableTools, unavailableTools } = describeTargetPlatform(backend);
+        const { availableTools, unavailableTools, unavailableOperations } = describeTargetPlatform(backend);
         const switchBackTarget = availableBackends.find((candidate) => candidate !== backend);
         const data = {
             success: true,
@@ -85,6 +86,7 @@ const platformOperationHandlers = {
             configuredBackends: availableBackends,
             availableTools,
             unavailableTools,
+            unavailableOperations,
             usageHint: switchBackTarget
                 ? `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`
                 : "No other backend is configured.",
@@ -111,6 +113,7 @@ export const platformModuleGroup = defineToolModule({
                 description: "Runtime backend selection operations.",
                 variants: [selectBackendSchema],
             }),
+            operationEffects: { select: "write" },
             tags: ["platform", "backend", "switch"],
             execute: createOperationDispatcher("c64_select_backend", platformOperationHandlers),
             examples: [

package/dist/tools/registry/printer.js

@@ -133,12 +133,13 @@ export const printerModuleGroup = defineToolModule({
                 description: "Printer operations available via the c64_printer tool.",
                 variants: printerOperations.map((operation) => operation.schema),
             }),
+            operationEffects: { print_text: "write", print_bitmap: "write", define_chars: "write" },
             tags: ["printer", "device", "grouped"],
             examples: [
                 {
                     name: "Print text",
                     description: "Generate BASIC for device 4",
-                    arguments: { op: "print_text", text: "HELLO", ensureReturn: true },
+                    arguments: { op: "print_text", text: "HELLO", target: "commodore", formFeed: true },
                 },
                 {
                     name: "Print bitmap",

package/dist/tools/registry/program.js

@@ -68,8 +68,12 @@ export const programModule = defineToolModule({
                 description: "Program operations available via the c64_program tool.",
                 variants: programOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                load_prg: "write", run_prg: "write", run_crt: "write", upload_run_basic: "write",
+                upload_run_asm: "write", batch_run: "write", bundle_run: "write", cross_platform_greeting: "write",
+            },
             tags: ["programs", "execution", "grouped"],
-            operationPlatforms: { load_prg: ["c64u", "u2"], run_crt: ["c64u", "u2"] },
+            operationPlatforms: { run_crt: ["c64u", "u2"] },
             operationToolNames: {
                 load_prg: "load_prg",
                 run_crt: "run_crt",

package/dist/tools/registry/rag.js

@@ -35,6 +35,7 @@ export const ragModuleGroup = defineToolModule({
                 description: "RAG operations available via the c64_rag tool.",
                 variants: ragOperations.map((operation) => operation.schema),
             }),
+            operationEffects: { basic: "read", asm: "read" },
             tags: ["rag", "reference", "grouped"],
             examples: [
                 {

package/dist/tools/registry/sound.js

@@ -4,10 +4,12 @@ import { audioModule } from "../audio.js";
 import { metaModule } from "../meta/index.js";
 import { literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
-import { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
+import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "../errors.js";
 import { jsonResult } from "../responses.js";
 const audioDescriptorIndex = buildDescriptorIndex(audioModule);
 const metaDescriptorIndex = buildDescriptorIndex(metaModule);
+/** Largest encoded PCM payload one capture_samples response may carry. */
+const MAX_SAMPLE_PAYLOAD_BYTES = 2 * 1024 * 1024;
 const captureSamplesArgsSchema = objectSchema({
     description: "Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.",
     properties: {
@@ -41,6 +43,10 @@ const soundOperations = [
                 });
                 const capture = await ctx.client.captureSamples({ count: parsed.count });
                 const samplesBuffer = Buffer.from(capture.samples.buffer, capture.samples.byteOffset, capture.samples.byteLength);
+                const encodedBytes = parsed.encoding === "hex" ? samplesBuffer.length * 2 : Math.ceil(samplesBuffer.length / 3) * 4;
+                if (encodedBytes > MAX_SAMPLE_PAYLOAD_BYTES) {
+                    throw new ToolValidationError(`Sample response would be ${encodedBytes} bytes, above the ${MAX_SAMPLE_PAYLOAD_BYTES} byte limit; lower count`, { path: "$.count", details: { count: parsed.count, encodedBytes, limitBytes: MAX_SAMPLE_PAYLOAD_BYTES } });
+                }
                 return jsonResult({
                     backend: capture.backend,
                     channels: capture.channels,
@@ -156,6 +162,11 @@ export const soundModuleGroup = defineToolModule({
                 description: "Sound operations available via the c64_sound tool.",
                 variants: soundOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                capture_samples: "read", set_volume: "write", reset: "write", note_on: "write", note_off: "write",
+                silence_all: "write", play_sid_file: "write", play_mod_file: "write", generate: "write",
+                compile_play: "write", play_preset: "write", pipeline: "write", analyze: "read", record_analyze: "read",
+            },
             tags: ["sid", "audio", "grouped"],
             operationPlatforms: {
                 capture_samples: ["c64u"],

package/dist/tools/registry/stream.js

@@ -5,7 +5,7 @@ const streamingDescriptorIndex = buildDescriptorIndex(streamingModule);
 const streamOperations = [
     {
         op: "start",
-        schema: extendSchemaWithOp("start", ensureDescriptor(streamingDescriptorIndex, "stream_start").inputSchema, { description: "Start an Ultimate streaming session toward a host:port target." }),
+        schema: extendSchemaWithOp("start", ensureDescriptor(streamingDescriptorIndex, "stream_start").inputSchema, { description: "Start an Ultimate streaming session. The device sends an unencrypted UDP stream to the target (IPv4 address or hostname, optional :port)." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(streamingModule, "stream_start", rawArgs, ctx),
     },
     {
@@ -34,6 +34,7 @@ export const streamModule = defineToolModule({
                 description: "Streaming operations available via the c64_stream tool.",
                 variants: streamOperations.map((operation) => operation.schema),
             }),
+            operationEffects: { start: "write", stop: "write" },
             tags: ["stream", "monitor", "grouped"],
             examples: [
                 {

package/dist/tools/registry/system.js

@@ -1,4 +1,5 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
+import { taskOperationEffect } from "../access.js";
 import { machineControlModule } from "../machineControl.js";
 import { metaModule } from "../meta/index.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
@@ -27,7 +28,7 @@ const systemOperations = [
     },
     {
         op: "poweroff",
-        schema: extendSchemaWithOp("poweroff", ensureDescriptor(machineDescriptorIndex, "poweroff").inputSchema, { description: "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off." }),
+        schema: extendSchemaWithOp("poweroff", ensureDescriptor(machineDescriptorIndex, "poweroff").inputSchema, { description: "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off. On C64U/U64 the machine cannot be restarted by software afterwards: power must be restored at the outlet, and it starts by itself only if automatic startup on power restoration is enabled." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "poweroff", rawArgs, ctx),
     },
     {
@@ -92,6 +93,12 @@ export const systemModuleGroup = defineToolModule({
                 description: "System operations available via the c64_system tool.",
                 variants: systemOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                pause: "write", resume: "write", reset: "write", reboot: "destructive", poweroff: "destructive",
+                power_cycle: "destructive", menu: "write", read_menu_screen: "read", start_task: "write",
+                stop_task: "write", stop_all_tasks: "write", list_tasks: "read", performance_report: "read",
+            },
+            effectOf: (op, args) => (op === "start_task" ? taskOperationEffect(args.operation) : undefined),
             tags: ["system", "control", "grouped"],
             operationPlatforms: { poweroff: ["c64u", "vice"], pause: ["c64u", "u2"], resume: ["c64u", "u2"], menu: ["c64u", "u2"], read_menu_screen: ["c64u", "u2"] },
             operationToolNames: { poweroff: "poweroff", pause: "pause", resume: "resume", menu: "menu_button", read_menu_screen: "read_menu_screen" },

package/dist/tools/schema.js

@@ -41,10 +41,10 @@ export function stringSchema(options = {}) {
         });
         const stringValue = value;
         if (options.minLength !== undefined && stringValue.length < options.minLength) {
-            throw new ToolValidationError(`String must have length ≥ ${options.minLength}`, { path, details: { minLength: options.minLength } });
+            throw new ToolValidationError(`String must have length ≥ ${options.minLength}`, { path, details: { minLength: options.minLength, received: stringValue.length } });
         }
         if (options.maxLength !== undefined && stringValue.length > options.maxLength) {
-            throw new ToolValidationError(`String must have length ≤ ${options.maxLength}`, { path, details: { maxLength: options.maxLength } });
+            throw new ToolValidationError(`String must have length ≤ ${options.maxLength}`, { path, details: { maxLength: options.maxLength, received: stringValue.length } });
         }
         if (options.pattern && !options.pattern.test(stringValue)) {
             throw new ToolValidationError("String does not match required pattern", {
@@ -55,7 +55,7 @@ export function stringSchema(options = {}) {
         if (options.enum && !options.enum.includes(stringValue)) {
             throw new ToolValidationError("Value must be one of the allowed options", {
                 path,
-                details: { allowed: options.enum },
+                details: { allowed: options.enum, received: stringValue },
             });
         }
         return stringValue;
@@ -86,13 +86,13 @@ export function numberSchema(options = {}) {
         if (options.minimum !== undefined && numberValue < options.minimum) {
             throw new ToolValidationError("Value is below minimum", {
                 path,
-                details: { minimum: options.minimum },
+                details: { minimum: options.minimum, received: numberValue },
             });
         }
         if (options.maximum !== undefined && numberValue > options.maximum) {
             throw new ToolValidationError("Value is above maximum", {
                 path,
-                details: { maximum: options.maximum },
+                details: { maximum: options.maximum, received: numberValue },
             });
         }
         return numberValue;
@@ -154,13 +154,13 @@ export function arraySchema(itemSchema, options = {}) {
         if (options.minItems !== undefined && result.length < options.minItems) {
             throw new ToolValidationError("Array has too few items", {
                 path,
-                details: { minItems: options.minItems },
+                details: { minItems: options.minItems, received: result.length },
             });
         }
         if (options.maxItems !== undefined && result.length > options.maxItems) {
             throw new ToolValidationError("Array has too many items", {
                 path,
-                details: { maxItems: options.maxItems },
+                details: { maxItems: options.maxItems, received: result.length },
             });
         }
         return result;

package/dist/tools/streaming.js

@@ -1,7 +1,7 @@
 import { defineToolModule } from "./types.js";
 import { objectSchema, stringSchema } from "./schema.js";
 import { textResult } from "./responses.js";
-import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 const streamIdentifierSchema = stringSchema({
     description: "Stream type to control (video/audio/debug).",
     enum: ["video", "audio", "debug"],
@@ -11,8 +11,8 @@ const streamStartArgsSchema = objectSchema({
     properties: {
         stream: streamIdentifierSchema,
         target: stringSchema({
-            description: "Destination host:port or UDP target understood by the firmware.",
-            minLength: 3,
+            description: "Destination of the UDP stream: IPv4 address or hostname with an optional :port (1-65535), e.g. 192.168.1.10, 192.168.1.10:11000 or pc.local:11000. The device sends the stream unencrypted over UDP to this address.",
+            minLength: 1,
         }),
     },
     required: ["stream", "target"],
@@ -26,6 +26,35 @@ const streamStopArgsSchema = objectSchema({
     required: ["stream"],
     additionalProperties: false,
 });
+const STREAM_TARGET_FORMS = "an IPv4 address or hostname with an optional :port (1-65535), e.g. 192.168.1.10, 192.168.1.10:11000 or pc.local:11000";
+const HOST_LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/;
+export function validateStreamTarget(target) {
+    const fail = () => {
+        throw new ToolValidationError(`Invalid parameter 'target' (${JSON.stringify(target)}): expected ${STREAM_TARGET_FORMS}.`, { path: "target" });
+    };
+    const parts = target.split(":");
+    if (parts.length > 2)
+        fail();
+    const [host, port] = parts;
+    if (port !== undefined) {
+        if (!/^\d{1,5}$/.test(port))
+            fail();
+        const n = Number(port);
+        if (n < 1 || n > 65535)
+            fail();
+    }
+    if (!host || host.length > 253)
+        fail();
+    const labels = host.split(".");
+    if (!labels.every((label) => HOST_LABEL.test(label)))
+        fail();
+    if (/^[\d.]+$/.test(host)) {
+        // Numeric-only: must be a proper dotted IPv4 address.
+        const octets = labels;
+        if (octets.length !== 4 || !octets.every((o) => /^\d{1,3}$/.test(o) && Number(o) <= 255))
+            fail();
+    }
+}
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -59,7 +88,7 @@ export const streamingModule = defineToolModule({
     tools: [
         {
             name: "stream_start",
-            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://guide/index for usage notes.",
+            description: "Start an Ultimate streaming session (video/audio/debug) sending an unencrypted UDP stream from the device to an IPv4 address or hostname with an optional :port. See c64://guide/index for usage notes.",
             summary: "Validates stream arguments and forwards the request to firmware, returning status metadata.",
             inputSchema: streamStartArgsSchema.jsonSchema,
             tags: ["stream", "start"],
@@ -74,6 +103,7 @@ export const streamingModule = defineToolModule({
             async execute(args, ctx) {
                 try {
                     const parsed = streamStartArgsSchema.parse(args ?? {});
+                    validateStreamTarget(parsed.target);
                     ctx.logger.info("Starting Ultimate stream", {
                         stream: parsed.stream,
                         target: parsed.target,