@ericsanchezok/meta-protocol 0.0.0-dev-202603301312 → 0.0.0-dev-202604050856

package/dist/bash.d.ts

@@ -51,6 +51,7 @@ export declare namespace MetaProtocolBash {
         envID: z.ZodString;
         tool: z.ZodLiteral<"bash">;
         action: z.ZodLiteral<"execute">;
+        sessionID: z.ZodString;
         payload: z.ZodObject<{
             command: z.ZodString;
             description: z.ZodString;
@@ -65,6 +66,8 @@ export declare namespace MetaProtocolBash {
         version: z.ZodLiteral<1>;
         requestID: z.ZodString;
         ok: z.ZodLiteral<true>;
+        tool: z.ZodLiteral<"bash">;
+        action: z.ZodLiteral<"execute">;
         result: z.ZodObject<{
             title: z.ZodString;
             metadata: z.ZodObject<{

package/dist/bash.js

@@ -31,10 +31,13 @@ export var MetaProtocolBash;
     MetaProtocolBash.ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
         tool: z.literal("bash"),
         action: z.literal("execute"),
+        sessionID: MetaProtocolEnv.SessionID,
         payload: MetaProtocolBash.ExecutePayload,
     });
-    MetaProtocolBash.ExecuteResult = MetaProtocolEnvelope.ResultBase.extend({
+    MetaProtocolBash.ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
         ok: z.literal(true),
+        tool: z.literal("bash"),
+        action: z.literal("execute"),
         result: MetaProtocolBash.Result,
     });
 })(MetaProtocolBash || (MetaProtocolBash = {}));

package/dist/bridge.d.ts

@@ -0,0 +1,4 @@
+export declare namespace MetaProtocolBridge {
+    const RequestEvent = "meta.execution.request";
+    const ResponseEvent = "meta.execution.response";
+}

package/dist/bridge.js

@@ -0,0 +1,5 @@
+export var MetaProtocolBridge;
+(function (MetaProtocolBridge) {
+    MetaProtocolBridge.RequestEvent = "meta.execution.request";
+    MetaProtocolBridge.ResponseEvent = "meta.execution.response";
+})(MetaProtocolBridge || (MetaProtocolBridge = {}));

package/dist/client.d.ts

@@ -1,9 +1,15 @@
 import type { MetaProtocolBash } from "./bash";
 import type { MetaProtocolEnv } from "./env";
 import type { MetaProtocolProcess } from "./process";
+import type { MetaProtocolSession } from "./session";
 export declare namespace MetaProtocolClient {
+    interface RemoteExecutionOptions {
+        sessionID?: MetaProtocolEnv.SessionID;
+        targetAgentID?: string;
+    }
     interface ExecutionClient {
-        executeBash(envID: MetaProtocolEnv.EnvID, input: MetaProtocolBash.ExecutePayload): Promise<MetaProtocolBash.Result>;
-        executeProcess(envID: MetaProtocolEnv.EnvID, input: MetaProtocolProcess.ExecutePayload): Promise<MetaProtocolProcess.Result>;
+        executeBash(envID: MetaProtocolEnv.EnvID, input: MetaProtocolBash.ExecutePayload, options?: RemoteExecutionOptions): Promise<MetaProtocolBash.Result>;
+        executeProcess(envID: MetaProtocolEnv.EnvID, input: MetaProtocolProcess.ExecutePayload, options?: RemoteExecutionOptions): Promise<MetaProtocolProcess.Result>;
+        executeSession(envID: MetaProtocolEnv.EnvID, input: MetaProtocolSession.ExecutePayload, options?: RemoteExecutionOptions): Promise<MetaProtocolSession.Result>;
     }
 }

package/dist/env.d.ts

@@ -2,6 +2,8 @@ import z from "zod";
 export declare namespace MetaProtocolEnv {
     const EnvID: z.ZodString;
     type EnvID = z.infer<typeof EnvID>;
+    const SessionID: z.ZodString;
+    type SessionID = z.infer<typeof SessionID>;
     const ProcessID: z.ZodString;
     type ProcessID = z.infer<typeof ProcessID>;
     const HostSessionID: z.ZodString;
@@ -12,5 +14,12 @@ export declare namespace MetaProtocolEnv {
         kind: "remote";
         envID: EnvID;
     };
+    type InvalidReason = "placeholder_alias" | "invalid_format";
+    class InvalidEnvIDError extends Error {
+        readonly envID: string;
+        readonly reason: InvalidReason;
+        constructor(envID: string, reason: InvalidReason);
+    }
+    function normalize(envID?: string): EnvID | undefined;
     function resolve(envID?: string): Target;
 }

package/dist/env.js

@@ -2,15 +2,73 @@ import z from "zod";
 export var MetaProtocolEnv;
 (function (MetaProtocolEnv) {
     MetaProtocolEnv.EnvID = z.string().min(1).describe("Execution environment ID");
+    MetaProtocolEnv.SessionID = z.string().min(1).describe("Remote collaboration session identifier");
     MetaProtocolEnv.ProcessID = z.string().min(1).describe("Opaque process identifier");
     MetaProtocolEnv.HostSessionID = z.string().min(1).describe("Remote host session identifier");
+    const LOCAL_ALIASES = new Set([
+        "local",
+        ":local",
+        "localhost",
+        "127.0.0.1",
+        "::1",
+        "loopback",
+        "self",
+        ":self",
+        "current",
+        ":current",
+        "host",
+        ":host",
+        "this",
+        ":this",
+    ]);
+    const PLACEHOLDER_ALIASES = new Set(["undefined", "null", "none", "nil", "n/a"]);
+    const ENVID_PREFIX = "env_";
+    class InvalidEnvIDError extends Error {
+        envID;
+        reason;
+        constructor(envID, reason) {
+            super(reason === "placeholder_alias"
+                ? `Invalid envID "${envID}". This looks like a placeholder value, not a real remote environment ID. ` +
+                    `For local execution, do NOT include the envID parameter at all — remove it from your tool call. ` +
+                    `For remote execution, pass a real remote envID such as "env_...".`
+                : `Invalid envID "${envID}". Remote environment IDs must start with "${ENVID_PREFIX}". ` +
+                    `For local execution, do NOT include the envID parameter at all — remove it from your tool call. ` +
+                    `Do not try to pass a value meaning "local" or "omit" — simply leave out the envID key entirely.`);
+            this.envID = envID;
+            this.reason = reason;
+            this.name = "MetaProtocolInvalidEnvIDError";
+        }
+    }
+    MetaProtocolEnv.InvalidEnvIDError = InvalidEnvIDError;
+    function normalize(envID) {
+        if (envID === undefined) {
+            return undefined;
+        }
+        const trimmed = envID.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        const lowered = trimmed.toLowerCase();
+        if (LOCAL_ALIASES.has(lowered)) {
+            return undefined;
+        }
+        if (PLACEHOLDER_ALIASES.has(lowered)) {
+            throw new InvalidEnvIDError(trimmed, "placeholder_alias");
+        }
+        if (!trimmed.startsWith(ENVID_PREFIX)) {
+            throw new InvalidEnvIDError(trimmed, "invalid_format");
+        }
+        return trimmed;
+    }
+    MetaProtocolEnv.normalize = normalize;
     function resolve(envID) {
-        if (!envID) {
+        const normalized = normalize(envID);
+        if (!normalized) {
             return { kind: "local" };
         }
         return {
             kind: "remote",
-            envID,
+            envID: normalized,
         };
     }
     MetaProtocolEnv.resolve = resolve;

package/dist/envelope.d.ts

@@ -3,6 +3,7 @@ export declare namespace MetaProtocolEnvelope {
     const Tool: z.ZodEnum<{
         bash: "bash";
         process: "process";
+        session: "session";
     }>;
     type Tool = z.infer<typeof Tool>;
     const RequestBase: z.ZodObject<{
@@ -12,6 +13,7 @@ export declare namespace MetaProtocolEnvelope {
         tool: z.ZodEnum<{
             bash: "bash";
             process: "process";
+            session: "session";
         }>;
         action: z.ZodString;
     }, z.core.$strip>;
@@ -22,10 +24,28 @@ export declare namespace MetaProtocolEnvelope {
         ok: z.ZodBoolean;
     }, z.core.$strip>;
     type ResultBase = z.infer<typeof ResultBase>;
+    const TypedResultBase: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        requestID: z.ZodString;
+        ok: z.ZodBoolean;
+        tool: z.ZodEnum<{
+            bash: "bash";
+            process: "process";
+            session: "session";
+        }>;
+        action: z.ZodString;
+    }, z.core.$strip>;
+    type TypedResultBase = z.infer<typeof TypedResultBase>;
     const ErrorResult: z.ZodObject<{
         version: z.ZodLiteral<1>;
         requestID: z.ZodString;
         ok: z.ZodLiteral<false>;
+        tool: z.ZodOptional<z.ZodEnum<{
+            bash: "bash";
+            process: "process";
+            session: "session";
+        }>>;
+        action: z.ZodOptional<z.ZodString>;
         error: z.ZodObject<{
             code: z.ZodEnum<{
                 env_not_found: "env_not_found";
@@ -41,6 +61,11 @@ export declare namespace MetaProtocolEnvelope {
                 host_internal_error: "host_internal_error";
                 stale_process_handle: "stale_process_handle";
                 stdin_unavailable: "stdin_unavailable";
+                session_required: "session_required";
+                session_invalid: "session_invalid";
+                session_busy: "session_busy";
+                session_refused: "session_refused";
+                session_caller_mismatch: "session_caller_mismatch";
             }>;
             message: z.ZodString;
             details: z.ZodOptional<z.ZodUnknown>;

package/dist/envelope.js

@@ -3,7 +3,7 @@ import { MetaProtocolEnv } from "./env";
 import { MetaProtocolError } from "./error";
 export var MetaProtocolEnvelope;
 (function (MetaProtocolEnvelope) {
-    MetaProtocolEnvelope.Tool = z.enum(["bash", "process"]);
+    MetaProtocolEnvelope.Tool = z.enum(["bash", "process", "session"]);
     MetaProtocolEnvelope.RequestBase = z.object({
         version: z.literal(1),
         requestID: z.string().min(1),
@@ -16,8 +16,14 @@ export var MetaProtocolEnvelope;
         requestID: z.string().min(1),
         ok: z.boolean(),
     });
+    MetaProtocolEnvelope.TypedResultBase = MetaProtocolEnvelope.ResultBase.extend({
+        tool: MetaProtocolEnvelope.Tool,
+        action: z.string().min(1),
+    });
     MetaProtocolEnvelope.ErrorResult = MetaProtocolEnvelope.ResultBase.extend({
         ok: z.literal(false),
+        tool: MetaProtocolEnvelope.Tool.optional(),
+        action: z.string().min(1).optional(),
         error: MetaProtocolError.Shape,
     });
 })(MetaProtocolEnvelope || (MetaProtocolEnvelope = {}));

package/dist/error.d.ts

@@ -14,6 +14,11 @@ export declare namespace MetaProtocolError {
         host_internal_error: "host_internal_error";
         stale_process_handle: "stale_process_handle";
         stdin_unavailable: "stdin_unavailable";
+        session_required: "session_required";
+        session_invalid: "session_invalid";
+        session_busy: "session_busy";
+        session_refused: "session_refused";
+        session_caller_mismatch: "session_caller_mismatch";
     }>;
     type Code = z.infer<typeof Code>;
     const Shape: z.ZodObject<{
@@ -31,6 +36,11 @@ export declare namespace MetaProtocolError {
             host_internal_error: "host_internal_error";
             stale_process_handle: "stale_process_handle";
             stdin_unavailable: "stdin_unavailable";
+            session_required: "session_required";
+            session_invalid: "session_invalid";
+            session_busy: "session_busy";
+            session_refused: "session_refused";
+            session_caller_mismatch: "session_caller_mismatch";
         }>;
         message: z.ZodString;
         details: z.ZodOptional<z.ZodUnknown>;

package/dist/error.js

@@ -15,6 +15,11 @@ export var MetaProtocolError;
         "host_internal_error",
         "stale_process_handle",
         "stdin_unavailable",
+        "session_required",
+        "session_invalid",
+        "session_busy",
+        "session_refused",
+        "session_caller_mismatch",
     ]);
     MetaProtocolError.Shape = z.object({
         code: MetaProtocolError.Code,

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export * from "./env";
 export * from "./error";
 export * from "./envelope";
+export * from "./bridge";
 export * from "./bash";
 export * from "./process";
+export * from "./session";
 export * from "./client";
 export * from "./host";

package/dist/index.js

@@ -1,7 +1,9 @@
 export * from "./env";
 export * from "./error";
 export * from "./envelope";
+export * from "./bridge";
 export * from "./bash";
 export * from "./process";
+export * from "./session";
 export * from "./client";
 export * from "./host";

package/dist/process.d.ts

@@ -184,6 +184,7 @@ export declare namespace MetaProtocolProcess {
             clear: "clear";
             remove: "remove";
         }>;
+        sessionID: z.ZodString;
         payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
             action: z.ZodLiteral<"list">;
         }, z.core.$strip>, z.ZodObject<{
@@ -220,6 +221,17 @@ export declare namespace MetaProtocolProcess {
         version: z.ZodLiteral<1>;
         requestID: z.ZodString;
         ok: z.ZodLiteral<true>;
+        tool: z.ZodLiteral<"process">;
+        action: z.ZodEnum<{
+            list: "list";
+            poll: "poll";
+            log: "log";
+            write: "write";
+            "send-keys": "send-keys";
+            kill: "kill";
+            clear: "clear";
+            remove: "remove";
+        }>;
         result: z.ZodObject<{
             title: z.ZodString;
             metadata: z.ZodObject<{

package/dist/process.js

@@ -80,10 +80,13 @@ export var MetaProtocolProcess;
     MetaProtocolProcess.ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
         tool: z.literal("process"),
         action: MetaProtocolProcess.Action,
+        sessionID: MetaProtocolEnv.SessionID,
         payload: MetaProtocolProcess.ExecutePayload,
     });
-    MetaProtocolProcess.ExecuteResult = MetaProtocolEnvelope.ResultBase.extend({
+    MetaProtocolProcess.ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
         ok: z.literal(true),
+        tool: z.literal("process"),
+        action: MetaProtocolProcess.Action,
         result: MetaProtocolProcess.Result,
     });
 })(MetaProtocolProcess || (MetaProtocolProcess = {}));

package/dist/session.d.ts

@@ -0,0 +1,144 @@
+import z from "zod";
+export declare namespace MetaProtocolSession {
+    const Action: z.ZodEnum<{
+        open: "open";
+        close: "close";
+        heartbeat: "heartbeat";
+    }>;
+    type Action = z.infer<typeof Action>;
+    const Status: z.ZodEnum<{
+        opened: "opened";
+        closed: "closed";
+        alive: "alive";
+        refused: "refused";
+        busy: "busy";
+    }>;
+    type Status = z.infer<typeof Status>;
+    const ExecutePayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        action: z.ZodLiteral<"open">;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodLiteral<"close">;
+        sessionID: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        action: z.ZodLiteral<"heartbeat">;
+        sessionID: z.ZodString;
+    }, z.core.$strip>], "action">;
+    type ExecutePayload = z.infer<typeof ExecutePayload>;
+    const ResultMetadata: z.ZodObject<{
+        action: z.ZodEnum<{
+            open: "open";
+            close: "close";
+            heartbeat: "heartbeat";
+        }>;
+        status: z.ZodEnum<{
+            opened: "opened";
+            closed: "closed";
+            alive: "alive";
+            refused: "refused";
+            busy: "busy";
+        }>;
+        sessionID: z.ZodOptional<z.ZodString>;
+        remoteAgentID: z.ZodOptional<z.ZodString>;
+        remoteOwnerUserID: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+        hostSessionID: z.ZodOptional<z.ZodString>;
+        envID: z.ZodOptional<z.ZodString>;
+        backend: z.ZodOptional<z.ZodEnum<{
+            local: "local";
+            remote: "remote";
+        }>>;
+    }, z.core.$strip>;
+    type ResultMetadata = z.infer<typeof ResultMetadata>;
+    const Result: z.ZodObject<{
+        title: z.ZodString;
+        metadata: z.ZodObject<{
+            action: z.ZodEnum<{
+                open: "open";
+                close: "close";
+                heartbeat: "heartbeat";
+            }>;
+            status: z.ZodEnum<{
+                opened: "opened";
+                closed: "closed";
+                alive: "alive";
+                refused: "refused";
+                busy: "busy";
+            }>;
+            sessionID: z.ZodOptional<z.ZodString>;
+            remoteAgentID: z.ZodOptional<z.ZodString>;
+            remoteOwnerUserID: z.ZodOptional<z.ZodNumber>;
+            label: z.ZodOptional<z.ZodString>;
+            hostSessionID: z.ZodOptional<z.ZodString>;
+            envID: z.ZodOptional<z.ZodString>;
+            backend: z.ZodOptional<z.ZodEnum<{
+                local: "local";
+                remote: "remote";
+            }>>;
+        }, z.core.$strip>;
+        output: z.ZodString;
+    }, z.core.$strip>;
+    type Result = z.infer<typeof Result>;
+    const ExecuteRequest: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        requestID: z.ZodString;
+        envID: z.ZodString;
+        tool: z.ZodLiteral<"session">;
+        action: z.ZodEnum<{
+            open: "open";
+            close: "close";
+            heartbeat: "heartbeat";
+        }>;
+        payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            action: z.ZodLiteral<"open">;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            action: z.ZodLiteral<"close">;
+            sessionID: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            action: z.ZodLiteral<"heartbeat">;
+            sessionID: z.ZodString;
+        }, z.core.$strip>], "action">;
+    }, z.core.$strip>;
+    type ExecuteRequest = z.infer<typeof ExecuteRequest>;
+    const ExecuteResult: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        requestID: z.ZodString;
+        ok: z.ZodLiteral<true>;
+        tool: z.ZodLiteral<"session">;
+        action: z.ZodEnum<{
+            open: "open";
+            close: "close";
+            heartbeat: "heartbeat";
+        }>;
+        result: z.ZodObject<{
+            title: z.ZodString;
+            metadata: z.ZodObject<{
+                action: z.ZodEnum<{
+                    open: "open";
+                    close: "close";
+                    heartbeat: "heartbeat";
+                }>;
+                status: z.ZodEnum<{
+                    opened: "opened";
+                    closed: "closed";
+                    alive: "alive";
+                    refused: "refused";
+                    busy: "busy";
+                }>;
+                sessionID: z.ZodOptional<z.ZodString>;
+                remoteAgentID: z.ZodOptional<z.ZodString>;
+                remoteOwnerUserID: z.ZodOptional<z.ZodNumber>;
+                label: z.ZodOptional<z.ZodString>;
+                hostSessionID: z.ZodOptional<z.ZodString>;
+                envID: z.ZodOptional<z.ZodString>;
+                backend: z.ZodOptional<z.ZodEnum<{
+                    local: "local";
+                    remote: "remote";
+                }>>;
+            }, z.core.$strip>;
+            output: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    type ExecuteResult = z.infer<typeof ExecuteResult>;
+}

package/dist/session.js

@@ -0,0 +1,49 @@
+import z from "zod";
+import { MetaProtocolEnvelope } from "./envelope";
+import { MetaProtocolEnv } from "./env";
+export var MetaProtocolSession;
+(function (MetaProtocolSession) {
+    MetaProtocolSession.Action = z.enum(["open", "close", "heartbeat"]);
+    MetaProtocolSession.Status = z.enum(["opened", "closed", "alive", "refused", "busy"]);
+    MetaProtocolSession.ExecutePayload = z.discriminatedUnion("action", [
+        z.object({
+            action: z.literal("open"),
+            label: z.string().optional(),
+        }),
+        z.object({
+            action: z.literal("close"),
+            sessionID: MetaProtocolEnv.SessionID,
+        }),
+        z.object({
+            action: z.literal("heartbeat"),
+            sessionID: MetaProtocolEnv.SessionID,
+        }),
+    ]);
+    MetaProtocolSession.ResultMetadata = z.object({
+        action: MetaProtocolSession.Action,
+        status: MetaProtocolSession.Status,
+        sessionID: MetaProtocolEnv.SessionID.optional(),
+        remoteAgentID: z.string().optional(),
+        remoteOwnerUserID: z.number().optional(),
+        label: z.string().optional(),
+        hostSessionID: MetaProtocolEnv.HostSessionID.optional(),
+        envID: MetaProtocolEnv.EnvID.optional(),
+        backend: z.enum(["local", "remote"]).optional(),
+    });
+    MetaProtocolSession.Result = z.object({
+        title: z.string(),
+        metadata: MetaProtocolSession.ResultMetadata,
+        output: z.string(),
+    });
+    MetaProtocolSession.ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
+        tool: z.literal("session"),
+        action: MetaProtocolSession.Action,
+        payload: MetaProtocolSession.ExecutePayload,
+    });
+    MetaProtocolSession.ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
+        ok: z.literal(true),
+        tool: z.literal("session"),
+        action: MetaProtocolSession.Action,
+        result: MetaProtocolSession.Result,
+    });
+})(MetaProtocolSession || (MetaProtocolSession = {}));

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@ericsanchezok/meta-protocol",
-  "version": "0.0.0-dev-202603301312",
+  "version": "0.0.0-dev-202604050856",
   "type": "module",
   "license": "MIT",
   "types": "./src/index.ts",

package/script/publish.ts

@@ -21,12 +21,18 @@ for (const [key, value] of Object.entries(pkg.exports)) {
 await Bun.write("package.json", JSON.stringify(pkg, null, 2))
 
 try {
-  const NPM_REGISTRY = "https://registry.npmjs.org"
-  await $`rm -f *.tgz`.nothrow()
-  await $`bun pm pack`
-  const tgz = (await $`ls *.tgz`.text()).trim()
-  const authFlag = process.env.NPM_TOKEN ? `--//registry.npmjs.org/:_authToken=${process.env.NPM_TOKEN}` : ""
-  await $`npm publish ${tgz} --tag ${Script.channel} --registry ${NPM_REGISTRY} --access public ${authFlag}`
+  if (await Script.npmVersionExists(pkg.name, Script.version)) {
+    console.log(`${pkg.name}@${Script.version} already published, skipping`)
+  } else {
+    const NPM_REGISTRY = "https://registry.npmjs.org"
+    await $`rm -f *.tgz`.nothrow()
+    await $`bun pm pack`
+    const tgz = (await $`ls *.tgz`.text()).trim()
+    const authFlag = process.env.NPM_TOKEN ? `--//registry.npmjs.org/:_authToken=${process.env.NPM_TOKEN}` : ""
+    await Script.retry(
+      () => $`npm publish ${tgz} --tag ${Script.channel} --registry ${NPM_REGISTRY} --access public ${authFlag}`,
+    )
+  }
 } finally {
   await Bun.write("package.json", JSON.stringify(original, null, 2))
 }

package/src/bash.ts

@@ -37,12 +37,15 @@ export namespace MetaProtocolBash {
   export const ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
     tool: z.literal("bash"),
     action: z.literal("execute"),
+    sessionID: MetaProtocolEnv.SessionID,
     payload: ExecutePayload,
   })
   export type ExecuteRequest = z.infer<typeof ExecuteRequest>
 
-  export const ExecuteResult = MetaProtocolEnvelope.ResultBase.extend({
+  export const ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
     ok: z.literal(true),
+    tool: z.literal("bash"),
+    action: z.literal("execute"),
     result: Result,
   })
   export type ExecuteResult = z.infer<typeof ExecuteResult>

package/src/bridge.ts

@@ -0,0 +1,4 @@
+export namespace MetaProtocolBridge {
+  export const RequestEvent = "meta.execution.request"
+  export const ResponseEvent = "meta.execution.response"
+}

package/src/client.ts

@@ -1,13 +1,29 @@
 import type { MetaProtocolBash } from "./bash"
 import type { MetaProtocolEnv } from "./env"
 import type { MetaProtocolProcess } from "./process"
+import type { MetaProtocolSession } from "./session"
 
 export namespace MetaProtocolClient {
+  export interface RemoteExecutionOptions {
+    sessionID?: MetaProtocolEnv.SessionID
+    targetAgentID?: string
+  }
+
   export interface ExecutionClient {
-    executeBash(envID: MetaProtocolEnv.EnvID, input: MetaProtocolBash.ExecutePayload): Promise<MetaProtocolBash.Result>
+    executeBash(
+      envID: MetaProtocolEnv.EnvID,
+      input: MetaProtocolBash.ExecutePayload,
+      options?: RemoteExecutionOptions,
+    ): Promise<MetaProtocolBash.Result>
     executeProcess(
       envID: MetaProtocolEnv.EnvID,
       input: MetaProtocolProcess.ExecutePayload,
+      options?: RemoteExecutionOptions,
     ): Promise<MetaProtocolProcess.Result>
+    executeSession(
+      envID: MetaProtocolEnv.EnvID,
+      input: MetaProtocolSession.ExecutePayload,
+      options?: RemoteExecutionOptions,
+    ): Promise<MetaProtocolSession.Result>
   }
 }

package/src/env.ts

@@ -4,6 +4,9 @@ export namespace MetaProtocolEnv {
   export const EnvID = z.string().min(1).describe("Execution environment ID")
   export type EnvID = z.infer<typeof EnvID>
 
+  export const SessionID = z.string().min(1).describe("Remote collaboration session identifier")
+  export type SessionID = z.infer<typeof SessionID>
+
   export const ProcessID = z.string().min(1).describe("Opaque process identifier")
   export type ProcessID = z.infer<typeof ProcessID>
 
@@ -12,13 +15,81 @@ export namespace MetaProtocolEnv {
 
   export type Target = { kind: "local" } | { kind: "remote"; envID: EnvID }
 
+  const LOCAL_ALIASES = new Set([
+    "local",
+    ":local",
+    "localhost",
+    "127.0.0.1",
+    "::1",
+    "loopback",
+    "self",
+    ":self",
+    "current",
+    ":current",
+    "host",
+    ":host",
+    "this",
+    ":this",
+  ])
+
+  const PLACEHOLDER_ALIASES = new Set(["undefined", "null", "none", "nil", "n/a"])
+
+  const ENVID_PREFIX = "env_"
+
+  export type InvalidReason = "placeholder_alias" | "invalid_format"
+
+  export class InvalidEnvIDError extends Error {
+    constructor(
+      readonly envID: string,
+      readonly reason: InvalidReason,
+    ) {
+      super(
+        reason === "placeholder_alias"
+          ? `Invalid envID "${envID}". This looks like a placeholder value, not a real remote environment ID. ` +
+              `For local execution, do NOT include the envID parameter at all — remove it from your tool call. ` +
+              `For remote execution, pass a real remote envID such as "env_...".`
+          : `Invalid envID "${envID}". Remote environment IDs must start with "${ENVID_PREFIX}". ` +
+              `For local execution, do NOT include the envID parameter at all — remove it from your tool call. ` +
+              `Do not try to pass a value meaning "local" or "omit" — simply leave out the envID key entirely.`,
+      )
+      this.name = "MetaProtocolInvalidEnvIDError"
+    }
+  }
+
+  export function normalize(envID?: string): EnvID | undefined {
+    if (envID === undefined) {
+      return undefined
+    }
+
+    const trimmed = envID.trim()
+    if (!trimmed) {
+      return undefined
+    }
+
+    const lowered = trimmed.toLowerCase()
+    if (LOCAL_ALIASES.has(lowered)) {
+      return undefined
+    }
+
+    if (PLACEHOLDER_ALIASES.has(lowered)) {
+      throw new InvalidEnvIDError(trimmed, "placeholder_alias")
+    }
+
+    if (!trimmed.startsWith(ENVID_PREFIX)) {
+      throw new InvalidEnvIDError(trimmed, "invalid_format")
+    }
+
+    return trimmed as EnvID
+  }
+
   export function resolve(envID?: string): Target {
-    if (!envID) {
+    const normalized = normalize(envID)
+    if (!normalized) {
       return { kind: "local" }
     }
     return {
       kind: "remote",
-      envID,
+      envID: normalized,
     }
   }
 }

package/src/envelope.ts

@@ -3,7 +3,7 @@ import { MetaProtocolEnv } from "./env"
 import { MetaProtocolError } from "./error"
 
 export namespace MetaProtocolEnvelope {
-  export const Tool = z.enum(["bash", "process"])
+  export const Tool = z.enum(["bash", "process", "session"])
   export type Tool = z.infer<typeof Tool>
 
   export const RequestBase = z.object({
@@ -22,8 +22,16 @@ export namespace MetaProtocolEnvelope {
   })
   export type ResultBase = z.infer<typeof ResultBase>
 
+  export const TypedResultBase = ResultBase.extend({
+    tool: Tool,
+    action: z.string().min(1),
+  })
+  export type TypedResultBase = z.infer<typeof TypedResultBase>
+
   export const ErrorResult = ResultBase.extend({
     ok: z.literal(false),
+    tool: Tool.optional(),
+    action: z.string().min(1).optional(),
     error: MetaProtocolError.Shape,
   })
   export type ErrorResult = z.infer<typeof ErrorResult>

package/src/error.ts

@@ -15,6 +15,11 @@ export namespace MetaProtocolError {
     "host_internal_error",
     "stale_process_handle",
     "stdin_unavailable",
+    "session_required",
+    "session_invalid",
+    "session_busy",
+    "session_refused",
+    "session_caller_mismatch",
   ])
   export type Code = z.infer<typeof Code>
 

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from "./env"
 export * from "./error"
 export * from "./envelope"
+export * from "./bridge"
 export * from "./bash"
 export * from "./process"
+export * from "./session"
 export * from "./client"
 export * from "./host"

package/src/process.ts

@@ -94,12 +94,15 @@ export namespace MetaProtocolProcess {
   export const ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
     tool: z.literal("process"),
     action: Action,
+    sessionID: MetaProtocolEnv.SessionID,
     payload: ExecutePayload,
   })
   export type ExecuteRequest = z.infer<typeof ExecuteRequest>
 
-  export const ExecuteResult = MetaProtocolEnvelope.ResultBase.extend({
+  export const ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
     ok: z.literal(true),
+    tool: z.literal("process"),
+    action: Action,
     result: Result,
   })
   export type ExecuteResult = z.infer<typeof ExecuteResult>

package/src/session.ts

@@ -0,0 +1,62 @@
+import z from "zod"
+import { MetaProtocolEnvelope } from "./envelope"
+import { MetaProtocolEnv } from "./env"
+
+export namespace MetaProtocolSession {
+  export const Action = z.enum(["open", "close", "heartbeat"])
+  export type Action = z.infer<typeof Action>
+
+  export const Status = z.enum(["opened", "closed", "alive", "refused", "busy"])
+  export type Status = z.infer<typeof Status>
+
+  export const ExecutePayload = z.discriminatedUnion("action", [
+    z.object({
+      action: z.literal("open"),
+      label: z.string().optional(),
+    }),
+    z.object({
+      action: z.literal("close"),
+      sessionID: MetaProtocolEnv.SessionID,
+    }),
+    z.object({
+      action: z.literal("heartbeat"),
+      sessionID: MetaProtocolEnv.SessionID,
+    }),
+  ])
+  export type ExecutePayload = z.infer<typeof ExecutePayload>
+
+  export const ResultMetadata = z.object({
+    action: Action,
+    status: Status,
+    sessionID: MetaProtocolEnv.SessionID.optional(),
+    remoteAgentID: z.string().optional(),
+    remoteOwnerUserID: z.number().optional(),
+    label: z.string().optional(),
+    hostSessionID: MetaProtocolEnv.HostSessionID.optional(),
+    envID: MetaProtocolEnv.EnvID.optional(),
+    backend: z.enum(["local", "remote"]).optional(),
+  })
+  export type ResultMetadata = z.infer<typeof ResultMetadata>
+
+  export const Result = z.object({
+    title: z.string(),
+    metadata: ResultMetadata,
+    output: z.string(),
+  })
+  export type Result = z.infer<typeof Result>
+
+  export const ExecuteRequest = MetaProtocolEnvelope.RequestBase.extend({
+    tool: z.literal("session"),
+    action: Action,
+    payload: ExecutePayload,
+  })
+  export type ExecuteRequest = z.infer<typeof ExecuteRequest>
+
+  export const ExecuteResult = MetaProtocolEnvelope.TypedResultBase.extend({
+    ok: z.literal(true),
+    tool: z.literal("session"),
+    action: Action,
+    result: Result,
+  })
+  export type ExecuteResult = z.infer<typeof ExecuteResult>
+}

package/test/env.test.ts

@@ -0,0 +1 @@
+export {}