Files
VCCPlusOSS/platforms/macos/Tools/MCP/MCPProjectTools.h
T
Brian Holman 5534005799 Sync VCC Plus 3.7.1 build 67 source
Refresh reviewed MCP output export, four-drive owned playtests, bounded BASIC readiness, and pinned CMOC 0.1.101 source/patches. Preserve independent source-edition identity, empty libraries, notices and privacy boundaries.

Validated 74 export/privacy checks, pinned dependency sources, and an independent unsigned universal Release build. A subsequent documentation-only correction removes an excluded qualification link; all build inputs remain identical.
2026-11-17 08:42:27 -07:00

264 lines
30 KiB
Objective-C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// SPDX-License-Identifier: GPL-3.0-or-later
#import "MCPGuestTools.h"
static NSArray<NSDictionary *> *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)]];
}
// Destination permission is granted natively and never inferred from Make access.
static NSArray<NSDictionary *> *MCPBuildExportTools() {
NSDictionary *id = @{@"type":@"string",@"minLength":@1,@"maxLength":@128};
NSDictionary *properties = @{@"project_id":id,@"build_id":id,@"artifact_id":id,
@"revision":@{@"type":@"integer",@"minimum":@0},@"destination_id":id,@"request_id":id,
@"output_ids":@{@"type":@"array",@"items":id,@"minItems":@1,@"maxItems":@64,@"uniqueItems":@YES}};
return @[
@{@"name":@"export_build_outputs",@"description":@"Deliver selected exportable_outputs from an exact successful build to its natively approved destination_id. Supply the original build revision and artifact_id, including for an earlier Release after building Debug. Creates a new exclusive delivery set; never replaces files. Returns export_id/status immediately; poll get_build_export. Retry the identical request_id to reuse and verify the original delivery. Changed selections conflict; changed source/destination bytes fail. No paths or arbitrary workspace files are accepted. Limits: 64 files, 64 MiB/file, 128 MiB/set, 512 MiB and 64 requests per connection, one active export.",
@"inputSchema":@{@"type":@"object",@"properties":properties,@"required":[properties.allKeys sortedArrayUsingSelector:@selector(compare:)],@"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@NO,@"openWorldHint":@NO}},
@{@"name":@"get_build_export",@"description":@"Poll one owned export_id. A completed receipt preserves original project/build/artifact/revision/configuration identities and reports delivered relative filenames, original sizes and SHA-256 hashes. Independently verify these bytes; an identical export retry verifies the existing delivery rather than silently repairing changes.",
@"inputSchema":@{@"type":@"object",@"properties":@{@"project_id":id,@"export_id":id},@"required":@[@"project_id",@"export_id"],@"additionalProperties":@NO},
@"annotations":@{@"readOnlyHint":@YES,@"openWorldHint":@NO}}
];
}
// Added only when the running app explicitly advertises project refresh.
static NSArray<NSDictionary *> *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<NSDictionary *> *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<NSDictionary *> *MCPPlaytestVideoTools() {
NSDictionary *identifier = @{ @"type":@"string", @"minLength":@1, @"maxLength":@64 };
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(@"start_playtest_video", @"Start a bounded MP4 recording of an owned disposable playtest's actual CoCo picture and optional generated CoCo audio. Does not advance execution: use ordinary playtest_input afterward. No microphone, Mac windows, personal emulator audio or capture UI cues are recorded. Maximum 3600 emulated fields (60 seconds), 64 MiB per clip, four clips and 256 MiB retained per run. Reuse an identical request_id on retry. Recordings end at their field/size limit with explicit truncation status; stop and retrieve the completed clip before restarting.",
@{ @"run_id":identifier, @"request_id":identifier, @"include_audio":@{ @"type":@"boolean", @"default":@YES },
@"max_fields":@{ @"type":@"integer", @"minimum":@1, @"maximum":@3600, @"default":@1800 } },
@[@"run_id", @"request_id"], NO),
tool(@"stop_playtest_video", @"Finish the current owned playtest recording without advancing the guest. Returns completed MP4 identity, byte count, SHA-256, actual field interval and truncation status. Retrying the identical request_id returns the same receipt. Remains available when ordinary mutation requests are exhausted; working files are retained if finalization fails.",
@{ @"run_id":identifier, @"request_id":identifier }, @[@"run_id", @"request_id"], NO),
tool(@"read_playtest_video", @"Read a completed MP4 belonging to this owned playtest in bounded base64 chunks. Assemble the chunks in offset order and verify the complete byte_count and SHA-256 from the receipt. Accepts only a clip_id returned by this run, never a host file path. Does not advance or change the guest.",
@{ @"run_id":identifier, @"clip_id":identifier,
@"offset":@{ @"type":@"integer", @"minimum":@0, @"maximum":@67108864, @"default":@0 },
@"limit":@{ @"type":@"integer", @"minimum":@1, @"maximum":@65536, @"default":@65536 } },
@[@"run_id", @"clip_id"], YES)
];
}
static NSArray<NSDictionary *> *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<NSDictionary *> *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<NSDictionary *> *MCPPlaytestMediaTools(BOOL multiDrive = NO) {
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" ] } };
if (multiDrive) {
NSDictionary *drive = @{@"type":@"integer",@"minimum":@0,@"maximum":@3,@"default":@0,
@"description":@"Target FD0–FD3. Omission means FD0; never wraps."};
NSMutableDictionary *insert = [insertProperties mutableCopy]; insert[@"drive"] = drive;
insert[@"write_protected"] = @{@"type":@"boolean",@"description":@"Optional owned-copy write protection. Omission preserves its setting; false cannot override format-imposed protection."};
insertProperties = insert;
NSMutableDictionary *eject = [ejectProperties mutableCopy]; eject[@"drive"] = drive; ejectProperties = 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":multiDrive ? @"Insert/eject only the selected drive FD0–FD3 (optional drive defaults to 0) in a paused owned run with the shared floppy controller idle. Insert requires reviewed media_id and exact current hash; optional boolean write_protected changes only that owned copy. Eject forbids media/hash/protection fields. Reject duplicate mounting of one writable copy. Old FD0 fields retain their meaning; drives lists all four placements, current/original hashes, generations, write protection and actual read/write byte transfers. Preserve all copies independently through exchange, cold restart, stop and retention. No reset, guest time advance, default-drive change or personal-session access. Reuse request_id only for the identical normalized drive/action/selection/protection plan." : @"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<NSDictionary *> *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;
}