oxtail 0.4.0

package/dist/transcripts.js

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync } from "node:fs";
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+function extractTextFromClaudeContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string") {
+            parts.push(b.text);
+        }
+    }
+    return parts.join("\n");
+}
+export function readClaudeTranscript(path, limit = 100) {
+    if (!existsSync(path)) {
+        return { messages: [], truncated: false, total_messages: 0 };
+    }
+    const raw = readFileSync(path, "utf8");
+    const messages = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (obj.type !== "user" && obj.type !== "assistant")
+            continue;
+        const role = obj.message?.role;
+        if (role !== "user" && role !== "assistant")
+            continue;
+        const text = extractTextFromClaudeContent(obj.message?.content);
+        if (!text)
+            continue;
+        messages.push({ role, text, timestamp: obj.timestamp ?? null });
+    }
+    const safeLimit = clamp(limit, 1, 1000);
+    const truncated = messages.length > safeLimit;
+    const tail = truncated ? messages.slice(-safeLimit) : messages;
+    return { messages: tail, truncated, total_messages: messages.length };
+}
+// Codex CLI injects two kinds of blocks into the first user message of a
+// rollout that look identical to user input at the role/type level:
+//   1. The AGENTS.md preamble, prefixed with the literal "# AGENTS.md
+//      instructions for " and wrapped in <INSTRUCTIONS>...</INSTRUCTIONS>.
+//   2. An <environment_context>...</environment_context> block.
+// Both prefixes are emitted by Codex itself, not typed by the user, so we
+// drop them at the block level — preserving any other blocks in the same
+// message in the unlikely case a real user authored mixed content.
+export function isCodexInjectedBlock(text) {
+    const t = text.trimStart();
+    if (t.startsWith("# AGENTS.md instructions for "))
+        return true;
+    const trimmed = text.trim();
+    if (trimmed.startsWith("<environment_context>") && trimmed.endsWith("</environment_context>")) {
+        return true;
+    }
+    return false;
+}
+function extractTextFromCodexContent(content) {
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if ((b.type === "input_text" || b.type === "output_text") && typeof b.text === "string") {
+            if (isCodexInjectedBlock(b.text))
+                continue;
+            parts.push(b.text);
+        }
+    }
+    return parts.join("\n");
+}
+export function readCodexTranscript(path, limit = 100) {
+    if (!existsSync(path)) {
+        return { messages: [], truncated: false, total_messages: 0 };
+    }
+    const raw = readFileSync(path, "utf8");
+    const messages = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (obj.type !== "response_item")
+            continue;
+        const p = obj.payload;
+        if (!p || p.type !== "message")
+            continue;
+        const role = p.role;
+        if (role !== "user" && role !== "assistant")
+            continue;
+        const text = extractTextFromCodexContent(p.content);
+        if (!text)
+            continue;
+        messages.push({ role, text, timestamp: obj.timestamp ?? null });
+    }
+    const safeLimit = clamp(limit, 1, 1000);
+    const truncated = messages.length > safeLimit;
+    const tail = truncated ? messages.slice(-safeLimit) : messages;
+    return { messages: tail, truncated, total_messages: messages.length };
+}

package/integrations/codex/oxtail-register/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: oxtail-register
+description: Register the current Codex agent session with the oxtail MCP peer registry. Use when the user asks to join oxtail, register with oxtail, run oxtail-register, fix oxtail client_session_id detection, or make this Codex session visible/readable to peer agents in the same project.
+---
+
+# Oxtail Register
+
+Register this Codex session with oxtail quickly and verify the result.
+
+## Communication Contract
+
+This workflow is meant to be lightweight. For routine success, do not narrate
+each internal step or paste diagnostic JSON. If a skill announcement is required,
+keep it to one short sentence. The final response should be only:
+
+```text
+Registered: <session_id>
+Transcript: <transcript_path>
+```
+
+If the session was already registered, use:
+
+```text
+Already registered: <session_id>
+Transcript: <transcript_path>
+```
+
+Only explain the detection strategy, environment variables, or fallback behavior
+when registration fails or the user explicitly asks.
+
+## Workflow
+
+1. Call `mcp__oxtail__get_my_session`.
+2. If `entry.client.session_id` is already non-null, report the compact "Already registered" result and stop.
+3. Run this shell command in the current project:
+
+   ```sh
+   printf '%s\n' "${CODEX_THREAD_ID:-$CODEX_COMPANION_SESSION_ID}"
+   ```
+
+4. If the command returns an empty string, do not scan transcripts unless the user asks. Report that Codex exposed neither `CODEX_THREAD_ID` nor `CODEX_COMPANION_SESSION_ID`.
+5. Call `mcp__oxtail__claim_session` with `{ "session_id": "<id from step 3>" }`. The response contains `session_id` and `transcript_path` directly — no extra verification call needed. Report the compact "Registered" result.
+
+Prefer `CODEX_THREAD_ID`; `CODEX_COMPANION_SESSION_ID` is only a compatibility fallback.

package/integrations/codex/oxtail-register/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Oxtail Register"
+  short_description: "Register Codex with oxtail peers"
+  default_prompt: "Use $oxtail-register to register this Codex session with the oxtail peer registry."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "oxtail"
+      description: "Local oxtail MCP server exposing session registration tools"

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "oxtail",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "description": "Coordination layer for parallel AI coding agent sessions, exposed over MCP.",
+  "main": "dist/server.js",
+  "bin": {
+    "oxtail": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "integrations",
+    ".claude/commands/oxtail-join.md",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "prepack": "rm -rf dist && npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d4j3y2k/oxtail.git"
+  },
+  "homepage": "https://github.com/d4j3y2k/oxtail#readme",
+  "bugs": {
+    "url": "https://github.com/d4j3y2k/oxtail/issues"
+  },
+  "author": "David Kim <d4j3y2k@gmail.com>",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "codex",
+    "tmux",
+    "agents",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  }
+}