Skip to main content
Glama
Sign In

Agenterm

by net.agenterm
OverviewDiscussionsAdmin

session_control

Destructive

Control an existing session with action=input, interrupt, eof or stop; does not create a new shell. Reuse session_id to preserve state while its shell lives. Every result includes action. input requires input text (no automatic newline) and returns accepted: the request was sent, not consumed or completed. Input reaches the program currently reading stdin. interrupt requests SIGINT for the terminal foreground process group on Linux/macOS, without forcibly stopping the whole session; Windows pipes do not support it. eof follows queued input: canonical Linux/macOS terminals receive their configured VEOF character, which may first flush pending input and require another EOF; raw mode or disabled VEOF is an error. Windows EOF permanently closes stdin while keeping output readable. EOF at a shell prompt may exit it. For interrupt/eof check list_clients.client_info.session_controls; delivered=true means the client acknowledged the OS operation within 5 seconds, not that the program stopped. stop cancels the whole session and accepts only optional wait_ms (default 1000, range 0–20000); done/status/canceled confirm the outcome. accepted alone never proves termination. If stop returns done=false, use session_read to check further state and output. Repeated stop does not resend pending cancellation and returns terminal state for an ended session; other actions error on ended sessions. Unknown or unauthorized sessions error. Only input accepts input; only stop accepts wait_ms. Input, interrupt and terminal EOF may repeat side effects; do not blindly retry. Timeout or cancellation can leave delivery uncertain. Use session_read to verify effects and drain output.

Input Schema

NameRequiredDescriptionDefault
inputNoRequired only for action=input; omit for other actions. Text is sent as provided without an added newline; include a newline to submit a shell command or prompt response.
actionYesOperation on this session: input sends stdin text (requires input); interrupt signals the foreground task; eof ends input according to platform semantics; stop cancels the entire session (optional wait_ms).
wait_msNoOnly for action=stop: maximum wait for a terminal result in milliseconds, 0–20000; default 1000. 0 returns a snapshot immediately. Omit for all other actions.
session_idYesSession identifier
client_tokenYesTarget client connection token, required with management access (including stdio and no-password mode). Device-scoped bearer access implicitly selects its own token.

Output Schema

NameRequiredDescriptionDefault
actionYesThe session_control action this result describes; determines which acknowledgment or terminal fields apply.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / oneOf
      Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "accepted": {
-        "description": "Whether the action was sent to the device connection; this does not confirm it was consumed or completed.",
-        "type": "boolean"
-      },
-      "action": {
-        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
-        "enum": [
-          "input"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "accepted",
-      "action"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
-        "enum": [
-          "interrupt"
-        ],
-        "type": "string"
-      },
-      "delivered": {
-        "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "delivered",
-      "action"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
-        "enum": [
-          "eof"
-        ],
-        "type": "string"
-      },
-      "delivered": {
-        "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "delivered",
-      "action"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "accepted": {
-        "description": "True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.",
-        "type": "boolean"
-      },
-      "action": {
-        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
-        "enum": [
-          "stop"
-        ],
-        "type": "string"
-      },
-      "already_done": {
-        "description": "True if the session was already ended when this stop call began; no new cancellation request is sent.",
-        "type": "boolean"
-      },
-      "canceled": {
-        "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
-        "type": [
-          "null",
-          "boolean"
-        ]
-      },
-      "done": {
-        "description": "True when a terminal result is available or the device connection closed; status and canceled identify the outcome.",
-        "type": "boolean"
-      },
-      "error": {
-        "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
-        "type": "string"
-      },
-      "exit_code": {
-        "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
-        "type": [
-          "null",
-          "integer"
-        ]
-      },
-      "next_action": {
-        "description": "Next step to perform. Invitation creation returns the exact tool call and deadline; other tools return human-readable guidance.",
-        "type": "string"
-      },
-      "session_id": {
-        "description": "Session identifier used by session_read and session_control.",
-        "type": "string"
-      },
-      "status": {
-        "description": "stopping: cancellation pending. stopped: terminal cancellation confirmed. finished: ended for another reason, including disconnection.",
-        "enum": [
-          "stopping",
-          "stopped",
-          "finished"
-        ],
-        "type": "string"
-      },
-      "timed_out": {
-        "description": "True if the target reported that the process execution timeout elapsed.",
-        "type": [
-          "null",
-          "boolean"
-        ]
-      }
-    },
-    "required": [
-      "session_id",
-      "accepted",
-      "done",
-      "status",
-      "already_done",
-      "action"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "accepted": {
+        "description": "Whether the action was sent to the device connection; this does not confirm it was consumed or completed.",
+        "type": "boolean"
+      },
+      "action": {
+        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+        "enum": [
+          "input"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "accepted",
+      "action"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+        "enum": [
+          "interrupt"
+        ],
+        "type": "string"
+      },
+      "delivered": {
+        "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "delivered",
+      "action"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+        "enum": [
+          "eof"
+        ],
+        "type": "string"
+      },
+      "delivered": {
+        "description": "True only after the client confirms it performed the requested signal or EOF operation. Does not guarantee the program consumed it, stopped or exited.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "delivered",
+      "action"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "accepted": {
+        "description": "True if a cancellation request was sent or is pending. False for a session already ended before this call. This alone never confirms termination.",
+        "type": "boolean"
+      },
+      "action": {
+        "description": "The session_control action this result describes; determines which acknowledgment or terminal fields apply.",
+        "enum": [
+          "stop"
+        ],
+        "type": "string"
+      },
+      "already_done": {
+        "description": "True if the session was already ended when this stop call began; no new cancellation request is sent.",
+        "type": "boolean"
+      },
+      "canceled": {
+        "description": "True only when the target reported cancellation; a disconnect alone does not confirm cancellation.",
+        "type": [
+          "null",
+          "boolean"
+        ]
+      },
+      "done": {
+        "description": "True when a terminal result is available or the device connection closed; status and canceled identify the outcome.",
+        "type": "boolean"
+      },
+      "error": {
+        "description": "Optional execution or connection error. A disconnect does not prove the remote process completed successfully.",
+        "type": "string"
+      },
+      "exit_code": {
+        "description": "Reported process exit code: 0 means success; -1 means execution failed, was interrupted, or the device disconnected before a normal exit report.",
+        "type": [
+          "null",
+          "integer"
+        ]
+      },
+      "session_id": {
+        "description": "Session identifier used by session_read and session_control.",
+        "type": "string"
+      },
+      "status": {
+        "description": "stopping: cancellation pending. stopped: terminal cancellation confirmed. finished: ended for another reason, including disconnection.",
+        "enum": [
+          "stopping",
+          "stopped",
+          "finished"
+        ],
+        "type": "string"
+      },
+      "timed_out": {
+        "description": "True if the target reported that the process execution timeout elapsed.",
+        "type": [
+          "null",
+          "boolean"
+        ]
+      }
+    },
+    "required": [
+      "session_id",
+      "accepted",
+      "done",
+      "status",
+      "already_done",
+      "action"
+    ],
+    "type": "object"
+  }
+]
  2. Added

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations (destructive, non-idempotent, open-world) by explaining what 'accepted' means, that input reaches whatever reads stdin, platform-specific SIGINT and EOF behavior, that EOF can exit a shell prompt, that stop's done=false requires session_read follow-up, and that timeout can leave delivery uncertain. It also warns against blind retries, matching the non-idempotent annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action list, but the rest is a dense run-on paragraph mixing platform rules, result semantics, and retry guidance. Almost every sentence carries information, yet the lack of structure makes it harder to scan than a complex tool warrants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity, annotations, 100% schema coverage, and an output schema, the description covers the operational caveats an agent needs: platform-specific behavior, uncertainty around accepted/delivered, retry safety, and ended-session behavior. Nothing critical is omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already documents input, action, wait_ms, and token semantics. The description still adds value by clarifying cross-action constraints ('Only input accepts input; only stop accepts wait_ms') and by giving behavioral meaning to the enum values (interrupt = SIGINT to foreground process group, eof = VEOF/raw-mode caveats).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Control an existing session') and enumerates all four actions. It immediately distinguishes itself from session creation with 'does not create a new shell', which separates it from session_start/create_client.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes verification to session_read ('Use session_read to verify effects and drain output') and names list_clients.client_info.session_controls as the precheck for interrupt/eof. It doesn't explicitly contrast when to choose eof vs stop vs session_start, but the action semantics make the selection largely evident.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Agenterm toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources