From 1fdb88a3559849681ea35fe9c9f3b52cab709548 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 25 May 2026 11:09:56 +0900 Subject: [PATCH] feat(help): #688 sandbox help JSON schema --- assets/help/sandbox.schema.json | 160 ++++++++++++++++++++++++++++++++ script/build-help-schemas.ts | 8 ++ src/help/schema/sandbox.ts | 53 +++++++++++ 3 files changed, 221 insertions(+) create mode 100644 assets/help/sandbox.schema.json create mode 100644 src/help/schema/sandbox.ts diff --git a/assets/help/sandbox.schema.json b/assets/help/sandbox.schema.json new file mode 100644 index 000000000..60c3e9768 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/script/build-help-schemas.ts b/script/build-help-schemas.ts index c705d3711..87588fb7d 100644 --- a/script/build-help-schemas.ts +++ b/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() { diff --git a/src/help/schema/sandbox.ts b/src/help/schema/sandbox.ts new file mode 100644 index 000000000..65fb0bc94 --- /dev/null +++ b/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 +export type SandboxExecution = z.infer +export type SandboxStatus = z.infer +export type SandboxResult = z.infer