codex-computer-use-mcp 0.1.0 → 0.3.0

package/dist/tools.js

@@ -0,0 +1,262 @@
+import { z } from "zod";
+const app = z.string().describe("App name, full app path, or unambiguous bundle identifier");
+const selectTextApp = z.string().describe("App name or bundle identifier");
+export const DIRECT_TOOL_SCHEMAS = {
+    list_apps: z.object({}).strict(),
+    get_app_state: z.object({ app }).strict(),
+    click: z
+        .object({
+        app,
+        click_count: z.number().refine(Number.isInteger).describe("Number of clicks. Defaults to 1").optional(),
+        element_index: z.string().describe("Element index to click").optional(),
+        mouse_button: z.enum(["left", "right", "middle"]).describe("Mouse button to click. Defaults to left.").optional(),
+        x: z.number().describe("X coordinate in screenshot pixel coordinates").optional(),
+        y: z.number().describe("Y coordinate in screenshot pixel coordinates").optional(),
+    })
+        .strict(),
+    perform_secondary_action: z
+        .object({
+        app,
+        element_index: z.string().describe("Element identifier"),
+        action: z.string().describe("Secondary accessibility action name"),
+    })
+        .strict(),
+    set_value: z
+        .object({
+        app,
+        element_index: z.string().describe("Element identifier"),
+        value: z.string().describe("Value to assign"),
+    })
+        .strict(),
+    select_text: z
+        .object({
+        app: selectTextApp,
+        element_index: z.string().describe("Text element identifier"),
+        text: z.string().describe("Target text as shown in the accessibility tree"),
+        prefix: z.string().describe("Optional text immediately before the target, used to disambiguate repeated matches").optional(),
+        selection: z.enum(["text", "cursor_before", "cursor_after"]).describe("Whether to select the text or place the cursor before or after it. Defaults to text.").optional(),
+        suffix: z.string().describe("Optional text immediately after the target, used to disambiguate repeated matches").optional(),
+    })
+        .strict(),
+    scroll: z
+        .object({
+        app,
+        element_index: z.string().describe("Element identifier"),
+        direction: z.string().describe("Scroll direction: up, down, left, or right"),
+        pages: z.number().describe("Number of pages to scroll. Fractional values are supported. Defaults to 1").optional(),
+    })
+        .strict(),
+    drag: z
+        .object({
+        app,
+        from_x: z.number().describe("Start X coordinate"),
+        from_y: z.number().describe("Start Y coordinate"),
+        to_x: z.number().describe("End X coordinate"),
+        to_y: z.number().describe("End Y coordinate"),
+    })
+        .strict(),
+    press_key: z.object({ app, key: z.string().describe("Key or key combination to press") }).strict(),
+    type_text: z.object({ app, text: z.string().describe("Literal text to type") }).strict(),
+};
+export const OFFICIAL_METHODS = Object.freeze(Object.keys(DIRECT_TOOL_SCHEMAS));
+const readAnnotations = Object.freeze({
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+});
+const actionAnnotations = Object.freeze({
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+});
+/** Exact upstream descriptions and annotations exposed by the signed Computer Use helper. */
+export const OFFICIAL_TOOL_METADATA = Object.freeze({
+    list_apps: {
+        description: "List the apps on this computer. Returns the set of apps that are currently running, as well as any that have been used in the last 14 days, including details on usage frequency",
+        annotations: readAnnotations,
+    },
+    get_app_state: {
+        description: "Start an app use session if needed, then get the state of the app's key window and return a screenshot and accessibility tree. This must be called once per assistant turn before interacting with the app",
+        annotations: readAnnotations,
+    },
+    click: {
+        description: "Click an element by index or pixel coordinates from screenshot",
+        annotations: actionAnnotations,
+    },
+    perform_secondary_action: {
+        description: "Invoke a secondary accessibility action exposed by an element",
+        annotations: actionAnnotations,
+    },
+    set_value: {
+        description: "Set the value of a settable accessibility element",
+        annotations: actionAnnotations,
+    },
+    select_text: {
+        description: "Select text inside a text element, or place the text cursor before or after it. Provide text exactly as it appears in the accessibility tree, including any Markdown formatting. If the text is not unique, provide surrounding prefix or suffix text to disambiguate it.",
+        annotations: actionAnnotations,
+    },
+    scroll: {
+        description: "Scroll an element in a direction by a number of pages",
+        annotations: actionAnnotations,
+    },
+    drag: {
+        description: "Drag from one point to another using pixel coordinates",
+        annotations: actionAnnotations,
+    },
+    press_key: {
+        description: "Press a key or key-combination on the keyboard, including modifier and navigation keys.\n  - This supports xdotool's `key` syntax.\n  - Examples: \"a\", \"Return\", \"Tab\", \"super+c\", \"Up\", \"KP_0\" (for the numpad 0 key).",
+        annotations: actionAnnotations,
+    },
+    type_text: {
+        description: "Type literal text using keyboard input",
+        annotations: actionAnnotations,
+    },
+});
+export const READ_ONLY_METHODS = new Set(OFFICIAL_METHODS.filter((method) => OFFICIAL_TOOL_METADATA[method].annotations.readOnlyHint));
+export const MUTATING_METHODS = new Set(OFFICIAL_METHODS.filter((method) => !READ_ONLY_METHODS.has(method)));
+export function isDirectMethod(value) {
+    return OFFICIAL_METHODS.includes(value);
+}
+const KEY_ALIASES = {
+    cmd: "Meta_L",
+    command: "Meta_L",
+    meta: "Meta_L",
+    ctrl: "Control_L",
+    control: "Control_L",
+    shift: "Shift_L",
+    alt: "Alt_L",
+    option: "Alt_L",
+    enter: "Return",
+    return: "Return",
+    esc: "Escape",
+    escape: "Escape",
+    backspace: "BackSpace",
+    delete: "Delete",
+    pageup: "Page_Up",
+    pagedown: "Page_Down",
+    arrowup: "Up",
+    arrowdown: "Down",
+    arrowleft: "Left",
+    arrowright: "Right",
+};
+export function normalizeKeyExpression(value) {
+    return value
+        .split("+")
+        .map((part) => {
+        const trimmed = part.trim();
+        const alias = KEY_ALIASES[trimmed.toLowerCase()];
+        if (alias)
+            return alias;
+        return /^[A-Z]$/.test(trimmed) ? trimmed.toLowerCase() : trimmed;
+    })
+        .join("+");
+}
+export function validateDirectArguments(method, value) {
+    const parsed = DIRECT_TOOL_SCHEMAS[method].parse(value);
+    if (method === "press_key")
+        return { ...parsed, key: normalizeKeyExpression(parsed.key) };
+    return parsed;
+}
+export function targetAppFor(method, args) {
+    return method === "list_apps" ? undefined : args.app;
+}
+/** Exact upstream MCP schemas observed from the signed helper. Drift fails closed before dispatch. */
+export const EXPECTED_OFFICIAL_INPUT_SCHEMAS = {
+    list_apps: { type: "object", properties: {}, additionalProperties: false },
+    get_app_state: {
+        type: "object",
+        properties: { app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" } },
+        required: ["app"],
+        additionalProperties: false,
+    },
+    click: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            click_count: { description: "Number of clicks. Defaults to 1", type: "integer" },
+            element_index: { description: "Element index to click", type: "string" },
+            mouse_button: { description: "Mouse button to click. Defaults to left.", enum: ["left", "right", "middle"], type: "string" },
+            x: { description: "X coordinate in screenshot pixel coordinates", type: "number" },
+            y: { description: "Y coordinate in screenshot pixel coordinates", type: "number" },
+        },
+        required: ["app"],
+        additionalProperties: false,
+    },
+    perform_secondary_action: {
+        type: "object",
+        properties: {
+            action: { description: "Secondary accessibility action name", type: "string" },
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            element_index: { description: "Element identifier", type: "string" },
+        },
+        required: ["app", "element_index", "action"],
+        additionalProperties: false,
+    },
+    set_value: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            element_index: { description: "Element identifier", type: "string" },
+            value: { description: "Value to assign", type: "string" },
+        },
+        required: ["app", "element_index", "value"],
+        additionalProperties: false,
+    },
+    select_text: {
+        type: "object",
+        properties: {
+            app: { description: "App name or bundle identifier", type: "string" },
+            element_index: { description: "Text element identifier", type: "string" },
+            prefix: { description: "Optional text immediately before the target, used to disambiguate repeated matches", type: "string" },
+            selection: { description: "Whether to select the text or place the cursor before or after it. Defaults to text.", enum: ["text", "cursor_before", "cursor_after"], type: "string" },
+            suffix: { description: "Optional text immediately after the target, used to disambiguate repeated matches", type: "string" },
+            text: { description: "Target text as shown in the accessibility tree", type: "string" },
+        },
+        required: ["app", "element_index", "text"],
+        additionalProperties: false,
+    },
+    scroll: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            direction: { description: "Scroll direction: up, down, left, or right", type: "string" },
+            element_index: { description: "Element identifier", type: "string" },
+            pages: { description: "Number of pages to scroll. Fractional values are supported. Defaults to 1", type: "number" },
+        },
+        required: ["app", "element_index", "direction"],
+        additionalProperties: false,
+    },
+    drag: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            from_x: { description: "Start X coordinate", type: "number" },
+            from_y: { description: "Start Y coordinate", type: "number" },
+            to_x: { description: "End X coordinate", type: "number" },
+            to_y: { description: "End Y coordinate", type: "number" },
+        },
+        required: ["app", "from_x", "from_y", "to_x", "to_y"],
+        additionalProperties: false,
+    },
+    press_key: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            key: { description: "Key or key combination to press", type: "string" },
+        },
+        required: ["app", "key"],
+        additionalProperties: false,
+    },
+    type_text: {
+        type: "object",
+        properties: {
+            app: { description: "App name, full app path, or unambiguous bundle identifier", type: "string" },
+            text: { description: "Literal text to type", type: "string" },
+        },
+        required: ["app", "text"],
+        additionalProperties: false,
+    },
+};
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC,CAAC;AAC7F,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC,CAAC;AAE3E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;IAChC,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACzC,KAAK,EAAE,CAAC;SACN,MAAM,CAAC;QACP,GAAG;QACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,iCAAiC,CAAC,CAAC,QAAQ,EAAE;QACvG,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;QACvE,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,0CAA0C,CAAC,CAAC,QAAQ,EAAE;QACjH,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC,CAAC,QAAQ,EAAE;QACjF,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC,CAAC,QAAQ,EAAE;KACjF,CAAC;SACD,MAAM,EAAE;IACV,wBAAwB,EAAE,CAAC;SACzB,MAAM,CAAC;QACP,GAAG;QACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;KAClE,CAAC;SACD,MAAM,EAAE;IACV,SAAS,EAAE,CAAC;SACV,MAAM,CAAC;QACP,GAAG;QACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;KAC7C,CAAC;SACD,MAAM,EAAE;IACV,WAAW,EAAE,CAAC;SACZ,MAAM,CAAC;QACP,GAAG,EAAE,aAAa;QAClB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAC7D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;QAC3E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oFAAoF,CAAC,CAAC,QAAQ,EAAE;QAC5H,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,sFAAsF,CAAC,CAAC,QAAQ,EAAE;QACxK,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mFAAmF,CAAC,CAAC,QAAQ,EAAE;KAC3H,CAAC;SACD,MAAM,EAAE;IACV,MAAM,EAAE,CAAC;SACP,MAAM,CAAC;QACP,GAAG;QACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACxD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QAC5E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2EAA2E,CAAC,CAAC,QAAQ,EAAE;KAClH,CAAC;SACD,MAAM,EAAE;IACV,IAAI,EAAE,CAAC;SACL,MAAM,CAAC;QACP,GAAG;QACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACjD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;KAC7C,CAAC;SACD,MAAM,EAAE;IACV,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;IAClG,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE;CAC/E,CAAC;AAKX,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAmB,CAAC,CAAC;AAYlG,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,KAAK;IACpB,YAAY,EAAE,IAAI;CAClB,CAAC,CAAC;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IACvC,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;IACpB,YAAY,EAAE,KAAK;CACnB,CAAC,CAAC;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,sBAAsB,GAAyD,MAAM,CAAC,MAAM,CAAC;IACzG,SAAS,EAAE;QACV,WAAW,EAAE,kLAAkL;QAC/L,WAAW,EAAE,eAAe;KAC5B;IACD,aAAa,EAAE;QACd,WAAW,EAAE,4MAA4M;QACzN,WAAW,EAAE,eAAe;KAC5B;IACD,KAAK,EAAE;QACN,WAAW,EAAE,gEAAgE;QAC7E,WAAW,EAAE,iBAAiB;KAC9B;IACD,wBAAwB,EAAE;QACzB,WAAW,EAAE,+DAA+D;QAC5E,WAAW,EAAE,iBAAiB;KAC9B;IACD,SAAS,EAAE;QACV,WAAW,EAAE,mDAAmD;QAChE,WAAW,EAAE,iBAAiB;KAC9B;IACD,WAAW,EAAE;QACZ,WAAW,EAAE,2QAA2Q;QACxR,WAAW,EAAE,iBAAiB;KAC9B;IACD,MAAM,EAAE;QACP,WAAW,EAAE,uDAAuD;QACpE,WAAW,EAAE,iBAAiB;KAC9B;IACD,IAAI,EAAE;QACL,WAAW,EAAE,wDAAwD;QACrE,WAAW,EAAE,iBAAiB;KAC9B;IACD,SAAS,EAAE;QACV,WAAW,EAAE,qOAAqO;QAClP,WAAW,EAAE,iBAAiB;KAC9B;IACD,SAAS,EAAE;QACV,WAAW,EAAE,wCAAwC;QACrD,WAAW,EAAE,iBAAiB;KAC9B;CACD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAe,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC;AACrJ,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAe,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAE3H,MAAM,UAAU,cAAc,CAAC,KAAa;IAC3C,OAAO,gBAAgB,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,WAAW,GAAqC;IACrD,GAAG,EAAE,QAAQ;IACb,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,WAAW;IACpB,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,OAAO;IACZ,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,OAAO;CACnB,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IACnD,OAAO,KAAK;SACV,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACjD,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QACxB,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAClE,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACb,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAAoB,EAAE,KAAc;IAC3E,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAwB,CAAC;IAC/E,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,sBAAsB,CAAC,MAAM,CAAC,GAAa,CAAC,EAAE,CAAC;IACpG,OAAO,MAAM,CAAC;AACf,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,IAAyB;IAC3E,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAAI,CAAC,GAA0B,CAAC;AAC9E,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,MAAM,+BAA+B,GAA4C;IACvF,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE;IAC1E,aAAa,EAAE;QACd,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,EAAE,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QACjH,QAAQ,EAAE,CAAC,KAAK,CAAC;QACjB,oBAAoB,EAAE,KAAK;KAC3B;IACD,KAAK,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,WAAW,EAAE,EAAE,WAAW,EAAE,iCAAiC,EAAE,IAAI,EAAE,SAAS,EAAE;YAChF,aAAa,EAAE,EAAE,WAAW,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxE,YAAY,EAAE,EAAE,WAAW,EAAE,0CAA0C,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC5H,CAAC,EAAE,EAAE,WAAW,EAAE,8CAA8C,EAAE,IAAI,EAAE,QAAQ,EAAE;YAClF,CAAC,EAAE,EAAE,WAAW,EAAE,8CAA8C,EAAE,IAAI,EAAE,QAAQ,EAAE;SAClF;QACD,QAAQ,EAAE,CAAC,KAAK,CAAC;QACjB,oBAAoB,EAAE,KAAK;KAC3B;IACD,wBAAwB,EAAE;QACzB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,MAAM,EAAE,EAAE,WAAW,EAAE,qCAAqC,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC9E,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,aAAa,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE;SACpE;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,CAAC;QAC5C,oBAAoB,EAAE,KAAK;KAC3B;IACD,SAAS,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,aAAa,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE;YACpE,KAAK,EAAE,EAAE,WAAW,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzD;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,CAAC;QAC3C,oBAAoB,EAAE,KAAK;KAC3B;IACD,WAAW,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,+BAA+B,EAAE,IAAI,EAAE,QAAQ,EAAE;YACrE,aAAa,EAAE,EAAE,WAAW,EAAE,yBAAyB,EAAE,IAAI,EAAE,QAAQ,EAAE;YACzE,MAAM,EAAE,EAAE,WAAW,EAAE,oFAAoF,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7H,SAAS,EAAE,EAAE,WAAW,EAAE,sFAAsF,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,cAAc,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE;YACnL,MAAM,EAAE,EAAE,WAAW,EAAE,mFAAmF,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC5H,IAAI,EAAE,EAAE,WAAW,EAAE,gDAAgD,EAAE,IAAI,EAAE,QAAQ,EAAE;SACvF;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,CAAC;QAC1C,oBAAoB,EAAE,KAAK;KAC3B;IACD,MAAM,EAAE;QACP,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,SAAS,EAAE,EAAE,WAAW,EAAE,4CAA4C,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxF,aAAa,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE;YACpE,KAAK,EAAE,EAAE,WAAW,EAAE,2EAA2E,EAAE,IAAI,EAAE,QAAQ,EAAE;SACnH;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,CAAC;QAC/C,oBAAoB,EAAE,KAAK;KAC3B;IACD,IAAI,EAAE;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,MAAM,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7D,MAAM,EAAE,EAAE,WAAW,EAAE,oBAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7D,IAAI,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE;YACzD,IAAI,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE;SACzD;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;QACrD,oBAAoB,EAAE,KAAK;KAC3B;IACD,SAAS,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,GAAG,EAAE,EAAE,WAAW,EAAE,iCAAiC,EAAE,IAAI,EAAE,QAAQ,EAAE;SACvE;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;QACxB,oBAAoB,EAAE,KAAK;KAC3B;IACD,SAAS,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACX,GAAG,EAAE,EAAE,WAAW,EAAE,2DAA2D,EAAE,IAAI,EAAE,QAAQ,EAAE;YACjG,IAAI,EAAE,EAAE,WAAW,EAAE,sBAAsB,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC7D;QACD,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;QACzB,oBAAoB,EAAE,KAAK;KAC3B;CACD,CAAC"}

package/docs/adr/0001-standalone-code-mode-mcp.md

@@ -0,0 +1,45 @@
+# ADR 0001: Keep Code Mode in a standalone MCP process
+
+- **Status:** Accepted
+- **Date:** 2026-07-15
+
+## Context
+
+Codex can compose MCP tools through JavaScript Code Mode. Pi's progressive tool disclosure reduces schema context but does not let generated code invoke arbitrary Pi tools. Adding an executor, loader, or batch method here would also break this repository's exact ten-tool Computer Use contract.
+
+We considered existing Pi and MCP implementations:
+
+- `pi-mcp-adapter` has the strongest Pi-facing MCP configuration, OAuth, elicitation, lifecycle, metadata, and rich-result handling, but no Code Mode executor.
+- `dmmulroy/pi-mcp` has a clean MCP manager but no Code Mode, no published package, and no detected licence.
+- `Hor1zonZzz/pi-codeMode` demonstrates Pi-side JavaScript orchestration but supports only reconstructed built-ins and has no MCP support or tests.
+- `pi-code-tool` is a tested Pi-native pattern, but uses Python/Monty and does not aggregate MCP servers.
+- Cloudflare's Code Mode packages are strong design references, but their secure executor depends on Cloudflare Dynamic Workers; `cloudflare/mcp` is specific to the Cloudflare API.
+- `tool-sandbox` and `tool-sandbox-mcp` provide QuickJS-based execution, but impose a separate capability boundary and the server primarily targets one upstream HTTP gateway.
+- `cmcp` is the closest standalone multi-server implementation, but lacks the OAuth, elicitation, sampling, roots, and notification fidelity required here.
+
+## Decision
+
+If we add Code Mode for Pi, implement it as a **separate stdio MCP server** loaded through Pi's existing MCP adapter.
+
+- Do not modify Pi core.
+- Do not add Code Mode methods to `codex-computer-use-mcp`; its public Computer Use surface remains the exact ten official tools.
+- Let the Code Mode process connect to upstream MCP servers and expose a compact code-execution surface for discovery and composition.
+- Give generated code the same filesystem, network, environment, and process authority as the Code Mode server's surrounding Pi environment. Do not add a stricter capability/security sandbox solely around Code Mode.
+- Use the standalone MCP process as the fault-containment boundary. Pi can time out, terminate, and restart it if generated code wedges the process. Do not add a child process or isolate per execution without operational evidence that the server boundary is insufficient.
+- Preserve upstream MCP behavior across the nested boundary, especially OAuth, cancellation, rich content, and elicitation responses. Never fabricate `accept` or `decline`; unsupported interaction returns `cancel`.
+
+Normal Pi tools remain available directly. This decision adds MCP composition; it does not attempt to turn every Pi tool into a nested Code Mode function.
+
+## Rationale
+
+The process boundary provides the practical reliability benefit—one malformed snippet cannot freeze Pi—without creating an artificial authority mismatch between Pi and Code Mode. A separate security sandbox would constrain only one route while the same agent can already use Pi's deliberately unrestricted tools.
+
+Keeping Code Mode separate also preserves this package's upstream contract, works with agent-agnostic MCP clients, and avoids coupling the implementation to Pi internals.
+
+## Consequences
+
+- Code Mode is a separate package and lifecycle from Computer Use.
+- The first implementation must close the protocol-fidelity gaps found in existing standalone proxies rather than adopting one unchanged.
+- Pi's MCP adapter remains responsible for the outer client connection and UI; the Code Mode server remains responsible for its upstream MCP connections and execution lifecycle.
+- Process timeout, termination, restart, cleanup, and end-to-end elicitation tests are release requirements.
+- Additional execution isolation remains an evidence-driven future option, not a default architectural requirement.

package/integrations/pi/README.md

@@ -1,50 +1,74 @@
-# Pi adapters
+# Pi integration
 
-Choose **one** integration path. Do not load both under the same tool name.
+The native Pi adapter is the primary 0.3 path. It registers ten namespaced typed tools so Pi itself chooses each official Computer Use method and argument. Pi 0.80.7 or newer exposes them progressively without changing the ten-tool contract.
 
-## Native Pi package adapter
+## Source checkout acceptance
 
 ```bash
-pi install npm:codex-computer-use-mcp@0.1.0
+npm ci
+npm run build
+CODEX_COMPUTER_USE_HOME="$(mktemp -d)" \
+  pi -ne -e /absolute/path/to/codex-computer-use-mcp/integrations/pi/index.ts
 ```
 
-The package manifest loads `integrations/pi/index.ts` and registers:
+`-ne` prevents an installed 0.1 adapter from loading at the same time. This source workflow does not install or switch live Pi configuration.
 
-- `background_computer_use`
-- `/background-computer-use-status`
-- `/background-computer-use-mode`
-
-The adapter imports the same compiled service used by the MCP server; it does not fork the security-critical runner or policy. Pi signals tool failures by thrown error, so cancellation text carries observed methods and non-retry guidance while the complete structured method list remains in the private audit.
-
-For a local checkout:
+For normal installation, use the exact version 0.3.0 npm package:
 
 ```bash
-npm ci && npm run build
-pi -ne -e /absolute/path/to/codex-computer-use-mcp/integrations/pi/index.ts
+pi install npm:codex-computer-use-mcp@0.3.0
 ```
 
-`-ne` avoids a duplicate-tool conflict if another copy is already installed.
+Use the source workflow only when you need to test an exact reviewed commit. Follow the rollback procedure in `MIGRATION.md` when replacing version 0.1.
+
+## Registered surface
+
+Initially active:
+
+- `computer_use_list_apps`
+- `computer_use_get_app_state`
+
+Registered and activated after a successful `get_app_state` call:
+
+- `computer_use_click`
+- `computer_use_perform_secondary_action`
+- `computer_use_set_value`
+- `computer_use_select_text`
+- `computer_use_scroll`
+- `computer_use_drag`
+- `computer_use_press_key`
+- `computer_use_type_text`
+
+Command:
+
+- `/computer-use-status`
+
+The session-start narrowing preserves every active tool owned by Pi or another extension. Activation after inspection is purely additive: both inspection tools remain active, and the adapter does not remove or replace any tool in that call. The lazily activated tools rely on their official descriptions and omit `promptSnippet` and `promptGuidelines`, so native deferred schema loading does not rebuild the system prompt. Supported Anthropic and OpenAI models receive the definitions at the inspection result; other models receive Pi's normal active-tool fallback on the next request.
 
-## Pi MCP gateway
+No-permissions is the only policy: all ten tools are registered and available through this lifecycle with no wrapper permission prompts, mode selector, or app/intent/action gate. The signed host runs with Codex Full access (`approvalPolicy: "never"`, `sandbox: "danger-full-access"`), so normal empty-schema Computer Use app approvals are accepted by Codex before they reach Pi. Pi renders any form, OpenAI-form, or URL elicitation app-server does emit. The user's `accept`, `decline`, or `cancel` response is returned unchanged; the adapter never fabricates one.
 
-Merge [`mcp.json.example`](mcp.json.example) into `~/.pi/agent/mcp.json`, then reload Pi.
+## Generic MCP gateway
 
-`directTools: false` is intentional. It keeps this powerful capability behind Pi's MCP gateway instead of injecting it into every agent turn as an always-on direct tool.
+Merge `mcp.json.example` only for the exact 0.3.0 package or after building an exact reviewed source commit. `directTools: false` is intentional; it keeps this powerful generic MCP surface behind Pi's gateway.
 
-For a local checkout, replace the command and arguments with:
+For a source checkout:
 
 ```json
 {
-  "command": "node",
-  "args": ["/absolute/path/to/codex-computer-use-mcp/dist/mcp-server.js"],
-  "lifecycle": "lazy",
-  "requestTimeoutMs": 360000,
-  "directTools": false
+  "mcpServers": {
+    "computer-use-direct-source": {
+      "command": "node",
+      "args": ["/absolute/path/to/codex-computer-use-mcp/dist/mcp-server.js"],
+      "lifecycle": "lazy",
+      "requestTimeoutMs": 180000,
+      "directTools": false
+    }
+  }
 }
 ```
 
-## Permission warning
+Do not load the native adapter and generic MCP adapter into the same acceptance process unless tool names are intentionally isolated.
 
-Standalone safe mode is list-only. `inspect`, `act`, and `dictionary_lookup` require explicitly acknowledged full-permissions mode. Full mode broadly authorizes wrapper use of official Computer Use because target checks cannot be placed before signed-client dispatch without breaking official sender authentication. Read the root README before enabling it.
+The generic MCP path uses the same durable no-permissions and official Full access policy: all ten methods and no wrapper permission gate. App-access approvals resolve inside Codex. Any standard form or URL elicitation app-server emits is forwarded to the invoking MCP client; an unsupported or headless client returns `cancel` rather than a fabricated decision.
 
-Do not register the app-bundled Codex broker itself as a direct tool. This wrapper provides signing checks, post-dispatch validation, focus monitoring, locking, cleanup criteria, and private audits.
+See the root `MIGRATION.md` before replacing an installed 0.1 adapter.