Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/guest-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <local file>`) 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 <local script>` 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
Expand Down
5 changes: 4 additions & 1 deletion internal/cli/session.go
Original file line number Diff line number Diff line change
Expand Up @@ -73,14 +73,17 @@ 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 <session-id> Read output chunks from a session")
fmt.Fprintln(w, " write <session-id> <data> Write input to a session")
fmt.Fprintln(w, " write <session-id> <data> Type terminal input or a short command (up to 64 KiB)")
fmt.Fprintln(w, " control <session-id> <key> Send a control key (ctrl-c, ctrl-d, enter, etc.)")
fmt.Fprintln(w, " wait <session-id> Wait for output settle or regex match")
fmt.Fprintln(w, " list List active and recent sessions")
fmt.Fprintln(w, " show <session-id> Show details of a session")
fmt.Fprintln(w, " close <session-id> Close a persistent session")
fmt.Fprintln(w, " approve <operation> Issue one exact, short-lived approval for agent:mcp-local")
fmt.Fprintln(w, " attach <session-id> Interactively attach to a session")
fmt.Fprintln(w, "")
fmt.Fprintln(w, "Files: amc guest prepare, then amc guest put --source <local file> (binary streaming, up to 1 TiB).")
fmt.Fprintln(w, "Local PowerShell scripts: amc guest exec --source <local script> (up to 16 MiB).")
}

func runSessionOpen(ctx context.Context, cl *client.Client, args []string, stdout, stderr io.Writer) int {
Expand Down
2 changes: 1 addition & 1 deletion internal/mcpadapter/adapter.go
Original file line number Diff line number Diff line change
Expand Up @@ -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{
Expand Down
8 changes: 4 additions & 4 deletions internal/mcpadapter/guest.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}

Expand Down Expand Up @@ -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" {
Expand Down
14 changes: 7 additions & 7 deletions internal/mcpadapter/testdata/schemas/tools.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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"
},
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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"
},
Expand Down Expand Up @@ -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": {
Expand All @@ -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": {
Expand Down
2 changes: 1 addition & 1 deletion internal/mcpadapter/types_sessions.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)"`
Expand Down
Loading