register

Instructions

Implementation Reference

• src/tools.js:21-39 (handler)

  The MCP tool handler for 'register' - calls the terminal register function and starts the lifecycle.

  server.tool(
    "register",
    "Register this terminal with a name (e.g. A1, A2). Other terminals can then send messages to this name.",
    { name: nameSchema.describe("Terminal name, e.g. A1, A2, dev, test") },
    async ({ name }) => {
      const result = register(name, pid);
      if (!result.ok) {
        return { content: [{ type: "text", text: result.reason }] };
      }
      lifecycle.start(name);
      return {
        content: [
          {
            type: "text",
            text: `Registered as "${name}". Other terminals can now send messages to "${name}".`,
          },
        ],
      };
    },

• src/tools.js:12-14 (schema)

  Zod schema for the 'name' input parameter of the register tool.

  const nameSchema = z
    .string()
    .regex(NAME_PATTERN, "Name must match [A-Za-z0-9_-]{1,32}");

• src/terminals.js:45-75 (helper)

  The actual registration logic: validates name, checks if name is already held by a live process, and writes the terminal record to disk atomically.

  export function register(name, pid, now = Date.now) {
    assertValidName(name);
    ensureDirs();
  
    const path = fileFor(name);
    const existing = /** @type {{pid?: number, heartbeat?: number} | null} */ (
      readJsonSafe(path)
    );
  
    if (existing && existing.pid && existing.pid !== pid) {
      const fresh =
        typeof existing.heartbeat === "number" &&
        now() - existing.heartbeat < STALE_AFTER_MS;
      if (fresh && isProcessAlive(String(existing.pid))) {
        return {
          ok: /** @type {const} */ (false),
          reason: `Name "${name}" is already held by pid ${existing.pid}.`,
        };
      }
    }
  
    writeJsonAtomic(path, {
      name,
      pid,
      registeredAt: existing?.pid === pid && /** @type {any} */ (existing).registeredAt
        ? /** @type {any} */ (existing).registeredAt
        : new Date(now()).toISOString(),
      heartbeat: now(),
    });
    return { ok: /** @type {const} */ (true) };
  }

• src/tools.js:20-40 (registration)

  The registerTools function that registers the 'register' tool (and others) onto the MCP server via server.tool().

  export function registerTools(server, { pid = process.pid, lifecycle }) {
    server.tool(
      "register",
      "Register this terminal with a name (e.g. A1, A2). Other terminals can then send messages to this name.",
      { name: nameSchema.describe("Terminal name, e.g. A1, A2, dev, test") },
      async ({ name }) => {
        const result = register(name, pid);
        if (!result.ok) {
          return { content: [{ type: "text", text: result.reason }] };
        }
        lifecycle.start(name);
        return {
          content: [
            {
              type: "text",
              text: `Registered as "${name}". Other terminals can now send messages to "${name}".`,
            },
          ],
        };
      },
    );

• src/validators.js:12-19 (helper)

  Validates terminal names against the NAME_PATTERN regex used by the register tool.

  export function assertValidName(name) {
    if (typeof name !== "string" || !NAME_PATTERN.test(name)) {
      throw new Error(
        `Invalid terminal name: must match ${NAME_PATTERN} (got ${JSON.stringify(name)})`,
      );
    }
    return name;
  }