diff --git a/docs/guest-operations.md b/docs/guest-operations.md index bed1a6a..d08020c 100644 --- a/docs/guest-operations.md +++ b/docs/guest-operations.md @@ -5,6 +5,16 @@ binary SSH worker. CLI and MCP call the same authenticated daemon application se PTY sessions remain available for terminal interaction, and `amc --direct` remains independent of the daemon and guest SSH. +Use `guest_put` (CLI: `amc guest put --source `) for every file upload, including +gigabyte archives and installers. It sends the entire file in one operation with bounded memory, +SHA-256 verification and a final durable receipt. Uploads support files up to 1 TiB. Prepare the +worker once with `guest_prepare`, then reuse it across transfers. `session_write` is terminal text +input with a 64 KiB per-call limit; splitting a file into terminal append commands adds a separate +dispatch, approval and receipt for each piece. That overhead can dominate the transfer time. + +For a local PowerShell script up to 16 MiB, use `amc guest exec --source ` with a new local +output destination. This sends and executes the complete script in one operation. + ## Authority and workspace The daemon resolves the enrolled target and its pinned SSH configuration. A client cannot supply diff --git a/internal/cli/session.go b/internal/cli/session.go index 8ae3e03..9b24598 100644 --- a/internal/cli/session.go +++ b/internal/cli/session.go @@ -73,7 +73,7 @@ func printSessionUsage(w io.Writer) { fmt.Fprintln(w, "Subcommands:") fmt.Fprintln(w, " open [target] Open a new persistent SSH terminal session on the enrolled target") fmt.Fprintln(w, " read Read output chunks from a session") - fmt.Fprintln(w, " write Write input to a session") + fmt.Fprintln(w, " write Type terminal input or a short command (up to 64 KiB)") fmt.Fprintln(w, " control Send a control key (ctrl-c, ctrl-d, enter, etc.)") fmt.Fprintln(w, " wait Wait for output settle or regex match") fmt.Fprintln(w, " list List active and recent sessions") @@ -81,6 +81,9 @@ func printSessionUsage(w io.Writer) { fmt.Fprintln(w, " close Close a persistent session") fmt.Fprintln(w, " approve Issue one exact, short-lived approval for agent:mcp-local") fmt.Fprintln(w, " attach Interactively attach to a session") + fmt.Fprintln(w, "") + fmt.Fprintln(w, "Files: amc guest prepare, then amc guest put --source (binary streaming, up to 1 TiB).") + fmt.Fprintln(w, "Local PowerShell scripts: amc guest exec --source (up to 16 MiB).") } func runSessionOpen(ctx context.Context, cl *client.Client, args []string, stdout, stderr io.Writer) int { diff --git a/internal/mcpadapter/adapter.go b/internal/mcpadapter/adapter.go index c7b3254..1738c00 100644 --- a/internal/mcpadapter/adapter.go +++ b/internal/mcpadapter/adapter.go @@ -265,7 +265,7 @@ func (a *Adapter) BuildServer() *mcp.Server { mcp.AddTool(server, &mcp.Tool{ Name: "session_write", - Description: "Write input data to a persistent terminal session", + Description: "Type terminal input or launch a short command (up to 64 KiB). Upload whole local files with guest_put; execute local scripts with guest_exec. Prepare their binary worker once with guest_prepare.", }, a.SessionWrite) mcp.AddTool(server, &mcp.Tool{ diff --git a/internal/mcpadapter/guest.go b/internal/mcpadapter/guest.go index 26c38a3..1c6c08f 100644 --- a/internal/mcpadapter/guest.go +++ b/internal/mcpadapter/guest.go @@ -86,10 +86,10 @@ func (a *Adapter) GuestRemoveOwned(ctx context.Context, _ *mcp.CallToolRequest, return a.guestOperation(ctx, in, "remove-owned") } func (a *Adapter) addGuestTools(server *mcp.Server) { - mcp.AddTool(server, &mcp.Tool{Name: "guest_prepare", InputSchema: guestInputSchema("prepare"), Description: "Explicitly prepare the enrolled guest worker using server-provisioned workspace identity"}, a.GuestPrepare) - mcp.AddTool(server, &mcp.Tool{Name: "guest_put", InputSchema: guestInputSchema("put"), Description: "Stream an explicit local source file and return an opaque guest ownership reference"}, a.GuestPut) + mcp.AddTool(server, &mcp.Tool{Name: "guest_prepare", InputSchema: guestInputSchema("prepare"), Description: "Prepare the persistent binary worker once before guest_put, guest_get or guest_exec; subsequent operations reuse it with the server-provisioned workspace identity"}, a.GuestPrepare) + mcp.AddTool(server, &mcp.Tool{Name: "guest_put", InputSchema: guestInputSchema("put"), Description: "Upload a whole local file, including gigabyte archives and installers (up to 1 TiB), in one binary stream with SHA-256 verification. Pass its source path after guest_prepare; returns an opaque ownership reference for guest_get and guest_remove_owned."}, a.GuestPut) mcp.AddTool(server, &mcp.Tool{Name: "guest_get", InputSchema: guestInputSchema("get"), Description: "Download an opaque owned artifact to a new local destination after verification"}, a.GuestGet) - mcp.AddTool(server, &mcp.Tool{Name: "guest_exec", InputSchema: guestInputSchema("exec"), Description: "Execute an explicit local UTF-8 script and publish verified output to a new local destination"}, a.GuestExec) + mcp.AddTool(server, &mcp.Tool{Name: "guest_exec", InputSchema: guestInputSchema("exec"), Description: "Send and execute a whole local UTF-8 PowerShell script (up to 16 MiB) through the prepared binary worker in one operation; publish verified output to a new local destination"}, a.GuestExec) mcp.AddTool(server, &mcp.Tool{Name: "guest_remove_owned", InputSchema: guestInputSchema("remove-owned"), Description: "Remove only artifacts identified by immutable opaque ownership references"}, a.GuestRemoveOwned) } @@ -131,7 +131,7 @@ func guestInputSchema(operation string) map[string]any { } required := []string{"reason", "idempotency_key", "deadline"} if operation == "put" || operation == "exec" { - properties["source"] = map[string]any{"type": "string", "minLength": 1, "description": "Explicit local payload path, never sent to the guest; exec accepts UTF-8 scripts up to 16 MiB"} + properties["source"] = map[string]any{"type": "string", "minLength": 1, "description": "Path to the complete local file; streamed as binary with bounded memory. Put accepts up to 1 TiB; exec accepts UTF-8 scripts up to 16 MiB. The local path stays on the host."} required = append(required, "source") } if operation == "get" || operation == "exec" { diff --git a/internal/mcpadapter/testdata/schemas/tools.json b/internal/mcpadapter/testdata/schemas/tools.json index 77cced8..fc47c0b 100644 --- a/internal/mcpadapter/testdata/schemas/tools.json +++ b/internal/mcpadapter/testdata/schemas/tools.json @@ -2353,7 +2353,7 @@ } }, { - "description": "Execute an explicit local UTF-8 script and publish verified output to a new local destination", + "description": "Send and execute a whole local UTF-8 PowerShell script (up to 16 MiB) through the prepared binary worker in one operation; publish verified output to a new local destination", "inputSchema": { "additionalProperties": false, "description": "guest_exec requires source, destination, max_output between 1 and 16777216 and no artifact_ids", @@ -2383,7 +2383,7 @@ "type": "string" }, "source": { - "description": "Explicit local payload path, never sent to the guest; exec accepts UTF-8 scripts up to 16 MiB", + "description": "Path to the complete local file; streamed as binary with bounded memory. Put accepts up to 1 TiB; exec accepts UTF-8 scripts up to 16 MiB. The local path stays on the host.", "minLength": 1, "type": "string" }, @@ -2889,7 +2889,7 @@ } }, { - "description": "Explicitly prepare the enrolled guest worker using server-provisioned workspace identity", + "description": "Prepare the persistent binary worker once before guest_put, guest_get or guest_exec; subsequent operations reuse it with the server-provisioned workspace identity", "inputSchema": { "additionalProperties": false, "description": "guest_prepare requires max_output=0 and no source, destination or artifact_ids", @@ -3141,7 +3141,7 @@ } }, { - "description": "Stream an explicit local source file and return an opaque guest ownership reference", + "description": "Upload a whole local file, including gigabyte archives and installers (up to 1 TiB), in one binary stream with SHA-256 verification. Pass its source path after guest_prepare; returns an opaque ownership reference for guest_get and guest_remove_owned.", "inputSchema": { "additionalProperties": false, "description": "guest_put requires source, max_output=0 and no destination or artifact_ids", @@ -3166,7 +3166,7 @@ "type": "string" }, "source": { - "description": "Explicit local payload path, never sent to the guest; exec accepts UTF-8 scripts up to 16 MiB", + "description": "Path to the complete local file; streamed as binary with bounded memory. Put accepts up to 1 TiB; exec accepts UTF-8 scripts up to 16 MiB. The local path stays on the host.", "minLength": 1, "type": "string" }, @@ -6098,7 +6098,7 @@ } }, { - "description": "Write input data to a persistent terminal session", + "description": "Type terminal input or launch a short command (up to 64 KiB). Upload whole local files with guest_put; execute local scripts with guest_exec. Prepare their binary worker once with guest_prepare.", "inputSchema": { "additionalProperties": false, "properties": { @@ -6107,7 +6107,7 @@ "type": "string" }, "data": { - "description": "Character data or command to write", + "description": "UTF-8 terminal input or short command, at most 65536 bytes; use guest_put for files and guest_exec for local scripts", "type": "string" }, "deadline": { diff --git a/internal/mcpadapter/types_sessions.go b/internal/mcpadapter/types_sessions.go index 6d8b08b..5b63134 100644 --- a/internal/mcpadapter/types_sessions.go +++ b/internal/mcpadapter/types_sessions.go @@ -45,7 +45,7 @@ type SessionReadResult struct { type SessionWriteInput struct { SessionID string `json:"session_id" jsonschema:"Session ID"` - Data string `json:"data" jsonschema:"Character data or command to write"` + Data string `json:"data" jsonschema:"UTF-8 terminal input or short command, at most 65536 bytes; use guest_put for files and guest_exec for local scripts"` Reason string `json:"reason" jsonschema:"Reason for writing data"` IdempotencyKey string `json:"idempotency_key" jsonschema:"Idempotency key"` Timeout string `json:"timeout" jsonschema:"Operation timeout (e.g. 30s, 5m)"`