feat(help): #688 sandbox help JSON schema

feat(help): #688 sandbox help JSON schema

assets/help/sandbox.schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/help/sandbox.schema.json",
+  "title": "Sandbox Environment",
+  "description": "JSON schema for oh-my-openagent sandbox execution environment output",
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "object",
+      "properties": {
+        "active": {
+          "type": "boolean",
+          "description": "Whether the sandbox runtime is active"
+        },
+        "uptime": {
+          "type": "number",
+          "description": "Runtime uptime in seconds"
+        },
+        "executionsTotal": {
+          "type": "number",
+          "description": "Total executions since start"
+        },
+        "executionsActive": {
+          "type": "number",
+          "description": "Currently active executions"
+        },
+        "config": {
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Whether sandbox is enabled"
+            },
+            "timeout": {
+              "type": "number",
+              "description": "Default execution timeout in seconds"
+            },
+            "memory": {
+              "description": "Memory limit (e.g., '512MB')",
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "network": {
+              "type": "boolean",
+              "description": "Whether network access is allowed"
+            },
+            "filesystem": {
+              "type": "object",
+              "properties": {
+                "read": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Readable paths"
+                },
+                "write": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Writable paths"
+                },
+                "tempDir": {
+                  "type": "string",
+                  "description": "Sandbox temporary directory"
+                }
+              },
+              "required": [
+                "read",
+                "write",
+                "tempDir"
+              ],
+              "additionalProperties": false,
+              "description": "Filesystem access rules"
+            }
+          },
+          "required": [
+            "enabled",
+            "timeout",
+            "network",
+            "filesystem"
+          ],
+          "additionalProperties": false,
+          "ref": "SandboxConfig",
+          "description": "Sandbox configuration"
+        }
+      },
+      "required": [
+        "active",
+        "uptime",
+        "executionsTotal",
+        "executionsActive",
+        "config"
+      ],
+      "additionalProperties": false,
+      "ref": "SandboxStatus",
+      "description": "Sandbox runtime status"
+    },
+    "recentExecutions": {
+      "description": "Recent execution records",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Execution ID"
+          },
+          "command": {
+            "type": "string",
+            "description": "Command that was executed"
+          },
+          "exitCode": {
+            "type": "number",
+            "description": "Process exit code"
+          },
+          "stdout": {
+            "type": "string",
+            "description": "Standard output"
+          },
+          "stderr": {
+            "type": "string",
+            "description": "Standard error"
+          },
+          "duration": {
+            "type": "number",
+            "description": "Execution duration in ms"
+          },
+          "sandboxed": {
+            "type": "boolean",
+            "description": "Whether execution was sandboxed"
+          }
+        },
+        "required": [
+          "id",
+          "command",
+          "exitCode",
+          "stdout",
+          "stderr",
+          "duration",
+          "sandboxed"
+        ],
+        "additionalProperties": false,
+        "ref": "SandboxExecution"
+      }
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "additionalProperties": false,
+  "ref": "SandboxResult"
+}

script/build-help-schemas.ts

@@ -2,6 +2,7 @@
 import { z } from "zod"
 import { DoctorResultSchema as DoctorSchema } from "../src/help/schema/doctor"
 import { StatusResultSchema as StatusSchema } from "../src/help/schema/status"
+import { SandboxResultSchema as SandboxSchema } from "../src/help/schema/sandbox"
 const SCHEMA_OUTPUT_DIR = "assets/help"
 
 interface SchemaEntry {
@@ -46,6 +47,13 @@ const SCHEMAS: SchemaEntry[] = [
     description: "JSON schema for oh-my-openagent system status output",
     id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/help/status.schema.json",
   },
+  {
+    name: "sandbox",
+    schema: SandboxSchema,
+    title: "Sandbox Environment",
+    description: "JSON schema for oh-my-openagent sandbox execution environment output",
+    id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/help/sandbox.schema.json",
+  },
 ]
 
 async function main() {

src/help/schema/sandbox.ts

@@ -0,0 +1,53 @@
+import { z } from "zod"
+
+/**
+ * Help JSON schema for the `sandbox` surface.
+ * Defines the structure of sandboxed execution environment output.
+ */
+export const SandboxConfigSchema = z
+  .object({
+    enabled: z.boolean().describe("Whether sandbox is enabled"),
+    timeout: z.number().describe("Default execution timeout in seconds"),
+    memory: z.string().nullable().optional().describe("Memory limit (e.g., '512MB')"),
+    network: z.boolean().describe("Whether network access is allowed"),
+    filesystem: z.object({
+      read: z.array(z.string()).describe("Readable paths"),
+      write: z.array(z.string()).describe("Writable paths"),
+      tempDir: z.string().describe("Sandbox temporary directory"),
+    }).describe("Filesystem access rules"),
+  })
+  .meta({ ref: "SandboxConfig" })
+
+export const SandboxExecutionSchema = z
+  .object({
+    id: z.string().describe("Execution ID"),
+    command: z.string().describe("Command that was executed"),
+    exitCode: z.number().describe("Process exit code"),
+    stdout: z.string().describe("Standard output"),
+    stderr: z.string().describe("Standard error"),
+    duration: z.number().describe("Execution duration in ms"),
+    sandboxed: z.boolean().describe("Whether execution was sandboxed"),
+  })
+  .meta({ ref: "SandboxExecution" })
+
+export const SandboxStatusSchema = z
+  .object({
+    active: z.boolean().describe("Whether the sandbox runtime is active"),
+    uptime: z.number().describe("Runtime uptime in seconds"),
+    executionsTotal: z.number().describe("Total executions since start"),
+    executionsActive: z.number().describe("Currently active executions"),
+    config: SandboxConfigSchema.describe("Sandbox configuration"),
+  })
+  .meta({ ref: "SandboxStatus" })
+
+export const SandboxResultSchema = z
+  .object({
+    status: SandboxStatusSchema.describe("Sandbox runtime status"),
+    recentExecutions: z.array(SandboxExecutionSchema).optional().describe("Recent execution records"),
+  })
+  .meta({ ref: "SandboxResult" })
+
+export type SandboxConfig = z.infer<typeof SandboxConfigSchema>
+export type SandboxExecution = z.infer<typeof SandboxExecutionSchema>
+export type SandboxStatus = z.infer<typeof SandboxStatusSchema>
+export type SandboxResult = z.infer<typeof SandboxResultSchema>