// SPDX-License-Identifier: GPL-3.0-or-later #import "MCPGuestTools.h" static NSArray *MCPProjectTools(BOOL assembly, BOOL interactive, BOOL customMake) { NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@128}; NSDictionary *requestID = @{@"type":@"string", @"minLength":@1, @"maxLength":assembly ? @64 : @128, @"description":assembly ? @"Unique request ID, up to 64 UTF-8 bytes." : @"Unique request ID, up to 128 UTF-8 bytes."}; NSDictionary *replacement = @{@"type":@"string", @"minLength":assembly ? @0 : @1, @"maxLength":assembly ? @1024 : @512, @"description":assembly ? @"One assembly line of up to 1024 UTF-8 bytes." : @"One ASCII C source line of up to 512 bytes, with printable characters or tabs."}; NSDictionary *path = @{@"type":@"string", @"minLength":@1, @"maxLength":@512}; NSDictionary *revision = @{@"type":@"integer", @"minimum":@0}; NSDictionary *scope = @{@"project_id":identifier, @"revision":revision}; NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, BOOL) = ^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, BOOL readOnly) { return @{@"name":name, @"description":description, @"inputSchema":@{@"type":@"object", @"properties":fields, @"required":[fields.allKeys sortedArrayUsingSelector:@selector(compare:)], @"additionalProperties":@NO}, @"annotations":@{@"readOnlyHint":@(readOnly), @"openWorldHint":@NO}}; }; NSDictionary *build = tool(@"build_project", @"Start a build of the selected revision. Reuse the request ID on retry. Poll get_build with the returned build ID.", @{@"project_id":identifier, @"revision":revision, @"request_id":requestID}, NO); if (customMake) { NSMutableDictionary *fields = [build[@"inputSchema"][@"properties"] mutableCopy]; fields[@"action"] = @{@"type":@"string", @"enum":@[@"build", @"disk"], @"description":@"Optional declared project action. Defaults to build. Arbitrary Make targets are not accepted."}; fields[@"configuration"] = @{@"type":@"string", @"minLength":@1, @"maxLength":@128, @"description":@"Optional configuration name from get_capabilities. Defaults to the selected workspace configuration."}; NSMutableDictionary *schema = [build[@"inputSchema"] mutableCopy]; schema[@"properties"] = fields; // Preserve the three original required arguments. NSMutableDictionary *customBuild = [build mutableCopy]; customBuild[@"inputSchema"] = schema; customBuild[@"description"] = @"Build the selected revision with the explicitly approved project Make recipe. Use only advertised actions and configurations. Reuse request_id only for the identical revision, action and configuration; poll get_build."; build = customBuild; } NSString *capabilities = assembly ? @"Identify the shared assembly project, target processor, files and revision." : customMake ? @"Identify the shared CMOC project, files, revision, approved Make recipe identity, declared actions, targets and configurations." : @"Identify the shared CMOC project, files and revision."; NSArray *tools = @[tool(@"get_capabilities", capabilities, @{}, YES), tool(@"read_project_file", @"Read one file named in the shared project manifest.", @{@"project_id":identifier, @"path":path}, YES), build, tool(@"get_build", @"Read the build state, compiler or assembler diagnostics and linked result.", @{@"build_id":identifier}, YES), tool(@"propose_fix", @"Submit one full replacement line for native review. Use the current revision and 1-based file line. Reuse the request ID on retry.", @{@"project_id":identifier, @"revision":revision, @"path":path, @"line_number":@{@"type":@"integer",@"minimum":@1}, @"replacement":replacement, @"request_id":requestID}, NO), tool(@"get_proposal", @"Read the user's decision on this proposed edit.", @{@"proposal_id":identifier}, YES), tool(@"get_run", @"Read guest execution or poll an accepted asynchronous playtest startup. A starting/cancelling result includes phase and busy; ready includes its receipt; failed includes phase and error. Use the project_id/revision from start_playtest.", scope, YES)]; if (!interactive) return tools; NSDictionary *keyRequestID = @{@"type":@"string", @"minLength":@1, @"maxLength":@64}; return [tools arrayByAddingObjectsFromArray:@[ tool(@"read_screen_text", @"Read the hardware text screen of the locally started, active compiled game. Live access ends on return to BASIC.", @{@"run_id":identifier}, YES), tool(@"send_keys", @"Send one letter, digit or space to the running game. Reuse request_id on retry. Up to 64 inputs per run.", @{@"run_id":identifier, @"request_id":keyRequestID, @"keys":MCPGuestKeySchema(NO)}, NO)]]; } // Added only when the running app explicitly advertises project refresh. static NSArray *MCPProjectRefreshTools() { NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@128}; NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, NSArray *, BOOL) = ^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, NSArray *required, BOOL readOnly) { return @{@"name":name, @"description":description, @"inputSchema":@{@"type":@"object", @"properties":fields, @"required":required, @"additionalProperties":@NO}, @"annotations":@{@"readOnlyHint":@(readOnly), @"openWorldHint":@NO}}; }; return @[ tool(@"refresh_project", @"Refresh captured project inputs after external edits. Existing authorized source changes can be accepted automatically; recipe, permissions, support scope or newly shared files require native review. Reuse request_id only for the identical request. Returns refresh_id and pending, approved, rejected or unchanged status; never executes a recipe.", @{@"project_id":identifier, @"request_id":identifier, @"revision":@{@"type":@"integer", @"minimum":@0}}, @[@"project_id", @"request_id", @"revision"], NO), tool(@"get_project_refresh", @"Poll a project refresh and its native review decision. Remains available while changed inputs block builds and runs.", @{@"project_id":identifier, @"refresh_id":identifier}, @[@"project_id", @"refresh_id"], YES), tool(@"read_project_inputs", @"Read the approved canonical input manifest: relative paths, roles, SHA-256 and permissions, plus current refresh status. This does not expose unapproved file contents or host paths. Page using offset and limit.", @{@"project_id":identifier, @"offset":@{@"type":@"integer", @"minimum":@0}, @"limit":@{@"type":@"integer", @"minimum":@1, @"maximum":@256}}, @[@"project_id"], YES) ]; } // Added only by a freshly exported diagnostics-aware C grant. static NSArray *MCPBuildDiagnosticTools() { return @[@{@"name":@"get_build_log", @"description":@"Read a retained, redacted build log in bounded UTF-8 byte pages. Use next_offset for the next page; logs disclose original process/retention truncation. This reads only a build belonging to this connection, never a host path.", @"inputSchema":@{@"type":@"object", @"properties":@{ @"build_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@128}, @"offset":@{@"type":@"integer",@"minimum":@0}, @"limit":@{@"type":@"integer",@"minimum":@1,@"maximum":@32768}}, @"required":@[@"build_id"],@"additionalProperties":@NO}, @"annotations":@{@"readOnlyHint":@YES,@"openWorldHint":@NO}}]; } static NSArray *MCPPlaytestAudioTools() { return @[@{@"name":@"capture_playtest_audio", @"description":@"Advance an owned disposable guest for 1 to 120 emulated fields and return its direct audio as PCM16 stereo WAV. Leaves the guest paused; verified stops can shorten the interval. Uses no microphone or personal emulator audio. Reuse request_id on retry to return the same clip without execution. Maximum 16 clips and 4 MiB retained WAV per run across boots; a maximum-clip allowance must remain before capture. Receipts include actual field interval, boot/run/artifact identity, sample count and SHA-256.", @"inputSchema":@{@"type":@"object", @"properties":@{ @"run_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64}, @"request_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64}, @"fields":@{@"type":@"integer",@"minimum":@1,@"maximum":@120}}, @"required":@[@"run_id",@"request_id",@"fields"],@"additionalProperties":@NO}, @"annotations":@{@"readOnlyHint":@NO,@"openWorldHint":@NO}}]; } // Fresh C owned-playtest grants only; never an arbitrary memory-read interface. static NSArray *MCPPlaytestCallContextTools() { NSDictionary *identifier = @{@"type":@"string", @"minLength":@1, @"maxLength":@64}; return @[@{@"name":@"get_call_context", @"description":@"Read bounded call context for a verified stopped owned disposable C run using its current snapshot. Returns only verified caller evidence; unsupported or ambiguous context is reported unavailable. Does not execute the guest or accept memory addresses.", @"inputSchema":@{@"type":@"object", @"properties":@{@"run_id":identifier, @"snapshot_id":identifier}, @"required":@[@"run_id", @"snapshot_id"], @"additionalProperties":@NO}, @"annotations":@{@"readOnlyHint":@YES, @"openWorldHint":@NO}}]; } // Fresh reviewed media-aware C playtest grants only. The two insertion fields // are action-specific in discovery as well as helper/host validation. static NSArray *MCPPlaytestMediaTools() { NSDictionary *identifier = @{ @"type":@"string", @"minLength":@1, @"maxLength":@64 }; NSDictionary *mediaID = @{ @"type":@"string", @"minLength":@1, @"maxLength":@64, @"pattern":@"^[A-Za-z0-9_-]{1,64}$", @"description":@"Opaque ID from list_playtest_media; never a host path." }; NSDictionary *sha = @{ @"type":@"string", @"minLength":@64, @"maxLength":@64, @"pattern":@"^[0-9a-f]{64}$", @"description":@"Exact current lowercase SHA-256 from the selected media listing." }; NSDictionary *listProperties = @{ @"project_id":identifier, @"revision":@{ @"type":@"integer", @"minimum":@0 }, @"artifact_id":identifier, @"run_id":identifier }; NSDictionary *insertProperties = @{ @"run_id":identifier, @"request_id":identifier, @"action":@{ @"type":@"string", @"enum":@[ @"insert" ] }, @"media_id":mediaID, @"media_sha256":sha }; NSDictionary *ejectProperties = @{ @"run_id":identifier, @"request_id":identifier, @"action":@{ @"type":@"string", @"enum":@[ @"eject" ] } }; NSMutableDictionary *exchangeProperties = [insertProperties mutableCopy]; exchangeProperties[@"action"] = @{ @"type":@"string", @"enum":@[ @"insert", @"eject" ] }; return @[ @{ @"name":@"list_playtest_media", @"description":@"List reviewed, hash-bound floppy media and compatible retained choices for the exact current project revision and build artifact. Optional run_id selects the current owned run's writable copies and their current hashes, mounted state and retention status. Listing does not advance or modify a guest. IDs are opaque; no host paths are exposed or accepted. Additional disk products must be declared in the reviewed project.", @"inputSchema":@{ @"type":@"object", @"properties":listProperties, @"required":@[ @"project_id", @"revision", @"artifact_id" ], @"additionalProperties":@NO }, @"annotations":@{ @"readOnlyHint":@YES, @"openWorldHint":@NO } }, @{ @"name":@"exchange_playtest_media", @"description":@"Insert or eject FD0 in a paused owned disposable run while its floppy controller is idle. Insert requires media_id and exact media_sha256 from that run's listing; eject forbids both. Uses only reviewed artifact-bound private writable disks, preserving every disk across swaps and restart and retaining all disks when the run stops. A successful exchange neither resets nor advances the guest; receipts identify old/new media, hashes, dirty/retained state and clock. Failed exchange preserves the mounted disk and data. Reuse request_id only for the identical action and selection; changed plans conflict. No arbitrary paths, personal media, memory or register writes.", @"inputSchema":@{ @"type":@"object", @"properties":exchangeProperties, @"required":@[ @"run_id", @"request_id", @"action" ], @"additionalProperties":@NO, @"oneOf":@[ @{ @"type":@"object", @"properties":insertProperties, @"required":@[ @"run_id", @"request_id", @"action", @"media_id", @"media_sha256" ], @"additionalProperties":@NO }, @{ @"type":@"object", @"properties":ejectProperties, @"required":@[ @"run_id", @"request_id", @"action" ], @"additionalProperties":@NO } ] }, @"annotations":@{ @"readOnlyHint":@NO, @"idempotentHint":@YES, @"openWorldHint":@NO } } ]; } // Available only through an explicit native owned-playtest connection grant. static NSArray *MCPPlaytestTools(BOOL processorSelection = NO, BOOL joystickInput = NO, BOOL mediaExchange = NO) { NSDictionary *id = @{@"type":@"string",@"minLength":@1,@"maxLength":@64}; NSDictionary *functionName = @{@"type":@"string",@"minLength":@1,@"maxLength":@1023}; NSDictionary *sha256 = @{@"type":@"string",@"minLength":@64,@"maxLength":@64,@"pattern":@"^[0-9a-f]{64}$", @"description":@"Exact lowercase SHA-256 from the retained test-disk receipt."}; NSDictionary *(^tool)(NSString *, NSString *, NSDictionary *, NSArray *, BOOL) = ^NSDictionary *(NSString *name, NSString *description, NSDictionary *fields, NSArray *required, BOOL readOnly) { return @{@"name":name,@"description":description,@"inputSchema":@{@"type":@"object",@"properties":fields, @"required":required,@"additionalProperties":@NO},@"annotations":@{@"readOnlyHint":@(readOnly),@"openWorldHint":@NO}}; }; NSDictionary *stopKind = @{@"type":@"string", @"enum":@[@"c_line", @"function_entry"], @"default":@"c_line", @"description":@"Optional stop mode. c_line requires a compiler-verified C statement; function_entry uses a verified object/linker function entry and may have no C source line."}; NSDictionary *step = @{@"type":@"object",@"properties":@{ @"keys":@{@"type":@"array",@"items":@{@"type":@"string",@"enum":@[@"a",@"b",@"c",@"d",@"e",@"f",@"g",@"h",@"i",@"j",@"k",@"l",@"m",@"n",@"o",@"p",@"q",@"r",@"s",@"t",@"u",@"v",@"w",@"x",@"y",@"z",@"0",@"1",@"2",@"3",@"4",@"5",@"6",@"7",@"8",@"9",@"up",@"down",@"left",@"backspace",@"right",@"space",@"period",@"enter",@"clear",@"break",@"alt",@"control",@"f1",@"f2",@"shift"]},@"maxItems":@8,@"uniqueItems":@YES}, @"fields":@{@"type":@"integer",@"minimum":@1,@"maximum":@600}}, @"required":@[@"keys",@"fields"],@"additionalProperties":@NO}; if (joystickInput) { NSMutableDictionary *properties = [step[@"properties"] mutableCopy]; NSDictionary *axis = @{@"type":@"integer",@"minimum":@0,@"maximum":@16383}; NSDictionary *joystick = @{@"type":@"object",@"properties":@{ @"port":@{@"type":@"string",@"enum":@[@"right",@"left"]}, @"x":axis, @"y":axis, @"buttons":@{@"type":@"array",@"items":@{@"type":@"string",@"enum":@[@"fire1",@"fire2"]},@"maxItems":@2,@"uniqueItems":@YES}}, @"required":@[@"port",@"x",@"y",@"buttons"],@"additionalProperties":@NO}; properties[@"joysticks"] = @{@"type":@"array",@"items":joystick,@"maxItems":@2,@"uniqueItems":@YES, @"description":@"Complete standard analog port states for this step. At most one entry per named port. Axes 0..16383, center 8191; X increases right, Y down. Missing ports center and release; omitted joysticks is keyboard-only with neutral ports."}; NSMutableDictionary *updatedStep = [step mutableCopy]; updatedStep[@"properties"] = properties; step = updatedStep; } NSMutableArray *tools = [@[ tool(@"start_playtest",@"Accept asynchronous startup of a disposable 512 KB MC6809 disk run of the exact current artifact. Returns a reserved run_id and starting status immediately; poll get_run(project_id, revision) until ready or failed, then use capture_playtest for an image. stop_playtest can cancel the reserved run_id during preparation or boot. No transport request waits for full startup. Personal session and media are preserved. Optional stop_function names a verified function. stop_kind defaults to c_line; function_entry stops at its verified object/linker entry without inventing a C line. stop_kind requires stop_function. To resume a retained writable test disk, supply both retained_disk_id and its exact prior receipt retained_disk_sha256; no host paths are accepted. Omit both for a fresh artifact disk. Reuse request_id on retry.", @{@"project_id":id,@"revision":@{@"type":@"integer",@"minimum":@0},@"artifact_id":id,@"request_id":id,@"stop_function":functionName,@"stop_kind":stopKind,@"retained_disk_id":id,@"retained_disk_sha256":sha256}, @[@"project_id",@"revision",@"artifact_id",@"request_id"],NO), tool(@"list_playtest_disks",@"List retained writable test disks recorded for the current shared project. Use a returned retained_disk_id and exact SHA-256 receipt with start_playtest. Older unscoped disks are not listed; a legacy resume requires its prior run ID and exact disk hash and reports legacy provenance. No host paths are exposed or accepted.", @{@"project_id":id},@[@"project_id"],YES), tool(@"playtest_input",@"Send held physical-key chords for bounded emulated video fields in the owned run (600 per step, 3600 per request, 216000 per run, 16 boots). Empty keys releases all keys. Resumes a verified stop. Reuse request_id only for an identical plan.", @{@"run_id":id,@"request_id":id,@"steps":@{@"type":@"array",@"items":step,@"minItems":@1,@"maxItems":@64}},@[@"run_id",@"request_id",@"steps"],NO), tool(@"playtest_debug",@"Pause, continue, instruction-step, or arm a verified named function in the owned run. stop_at requires function; optional stop_kind defaults to c_line, or function_entry uses its verified object/linker entry without claiming a C statement. Other actions do not accept function or stop_kind. No registers or guest memory can be written.", @{@"run_id":id,@"request_id":id,@"action":@{@"type":@"string",@"enum":@[@"pause",@"continue",@"step",@"stop_at"]},@"function":functionName,@"stop_kind":stopKind},@[@"run_id",@"request_id",@"action"],NO), tool(@"capture_playtest",@"Capture the owned run's framebuffer, field clock and disk identity without advancing it.",@{@"run_id":id},@[@"run_id"],YES), tool(@"capture_playtest_graphics",@"Capture a read-only graphics preview at one paused owned-machine state. Returns current display-buffer physical identity and its PNG; optional buffer_id selects one framebuffer declared by this artifact's verified manifest for a second PNG, including a bounded current_gime canvas. Uses current video registers, not a historical presented frame. Accepts no addresses and never advances or edits the guest.", @{@"run_id":id,@"buffer_id":@{@"type":@"string",@"minLength":@1,@"maxLength":@64,@"pattern":@"^[A-Za-z0-9_-]{1,64}$"}},@[@"run_id"],YES), tool(@"restart_playtest",@"Cold restart only the owned run, retaining its writable test disk and repeating its declared boot commands. Reuse request_id on retry.",@{@"run_id":id,@"request_id":id},@[@"run_id",@"request_id"],NO), tool(@"stop_playtest",@"Cancel a pending startup by its reserved run_id, or stop the owned worker and retain its test disk in VCC Plus development results. Pending cancellation is polled with get_run until busy is false; a late worker is cleaned up before replacement. Personal media remain untouched.",@{@"run_id":id,@"request_id":id},@[@"run_id",@"request_id"],NO) ] mutableCopy]; if (joystickInput) { NSMutableDictionary *input = [tools[2] mutableCopy]; input[@"description"] = @"Apply complete keyboard and standard analog joystick states for bounded emulated fields in this owned run. At most two distinct ports, axis range 0..16383, center 8191, fire1/fire2. Missing ports center/release. Inputs release after the plan, interrupted stops or errors. Limits: 64 steps, 600 fields per step, 3600 per request; budgets/ownership remain enforced. Reuse request_id only for an identical plan. Receipts include actual input and bounded per-step input_trace; no guest memory/register writes."; tools[2] = input; [tools addObject:tool(@"get_playtest_input", @"Read the owned worker's actual current keyboard-held flag and two standard analog port snapshots without advancing, changing input or consuming execution budget. Completed plans report neutral released input; input_trace in the input receipt describes applied step states.", @{@"run_id":id}, @[@"run_id"], YES)]; } if (mediaExchange) { NSMutableDictionary *start = [tools[0] mutableCopy]; NSMutableDictionary *schema = [start[@"inputSchema"] mutableCopy]; NSMutableDictionary *properties = [schema[@"properties"] mutableCopy]; properties[@"retained_media"] = @{ @"type":@"array", @"minItems":@1, @"maxItems":@8, @"uniqueItems":@YES, @"description":@"Optional retained writable copies for distinct additional media_id values from the current artifact listing. Omit for fresh additional disks; primary disk resumption still uses retained_disk_id and retained_disk_sha256. Exact per-disk provenance and hashes are rechecked before startup.", @"items":@{ @"type":@"object", @"properties":@{ @"media_id":@{ @"type":@"string", @"minLength":@1, @"maxLength":@64, @"pattern":@"^[A-Za-z0-9_-]{1,64}$" }, @"retained_disk_id":id, @"retained_disk_sha256":sha256 }, @"required":@[ @"media_id", @"retained_disk_id", @"retained_disk_sha256" ], @"additionalProperties":@NO } }; schema[@"properties"] = properties; start[@"inputSchema"] = schema; start[@"description"] = [start[@"description"] stringByAppendingString:@" Fresh media-aware grants may additionally resume declared disks through retained_media; each run keeps independent writable copies. stop_playtest retains all of those copies, including unmounted media."]; tools[0] = start; } if (!processorSelection) return tools; NSMutableArray *updated = [tools mutableCopy]; NSMutableDictionary *start = [tools[0] mutableCopy]; NSMutableDictionary *schema = [start[@"inputSchema"] mutableCopy]; NSMutableDictionary *properties = [schema[@"properties"] mutableCopy]; properties[@"processor"] = @{@"type":@"string",@"enum":@[@"MC6809",@"HD6309"],@"default":@"MC6809", @"description":@"Guest CPU, independent of host architecture. Omission selects MC6809. HD6309 starts in reset emulation mode; the guest controls MD/native mode. Restart retains this CPU. A changed CPU requires a new start request_id."}; schema[@"properties"] = properties; start[@"inputSchema"] = schema; start[@"description"] = [start[@"description"] stringByReplacingOccurrencesOfString:@"512 KB MC6809 disk run" withString:@"512 KB disk run using processor MC6809 (default) or HD6309"]; updated[0] = start; return updated; }