ticlawk-connector 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 ticlawk
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# ticlawk-connector
+
+Local connector for pairing Claude Code and OpenClaw agents with ticlawk.
+
+Status: alpha
+
+## Install
+
+```bash
+npx ticlawk-connector start
+```
+
+The connector reads config from `~/.ticlawk/.config`.
+
+## Commands
+
+```bash
+npx ticlawk-connector start
+npx ticlawk-connector health
+npx ticlawk-connector config-path
+npx ticlawk-connector pair --code 123456 --session-id <claude-session-id>
+npx ticlawk-connector pair --code 123456 --type openclaw --channel-id myskills --name myskills
+```
+
+## Config
+
+Example `~/.ticlawk/.config`:
+
+```bash
+TICLAWK_API_KEY=tk_xxxx
+TICLAWK_API_URL=https://ticlawk.com
+GATEWAY_HOST=127.0.0.1
+GATEWAY_PORT=18789
+CC_COMPACT_THRESHOLD=500000
+FEED_RELAY_PORT=3002
+```
+
+`TICLAWK_API_KEY` is written automatically after successful pairing.

package/bin/ticlawk-connector.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { request } from 'node:http';
+import { startConnector, TICLAWK_CONFIG_PATH } from '../ticlawk-connector.mjs';
+
+function printUsage() {
+  console.log(`ticlawk-connector
+
+Usage:
+  ticlawk-connector start
+  ticlawk-connector health
+  ticlawk-connector pair --code <code> --session-id <id>
+  ticlawk-connector pair --code <code> --type openclaw --channel-id <id> [--name <name>]
+  ticlawk-connector config-path
+`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      args[key] = value;
+    } else {
+      args._.push(arg);
+    }
+  }
+  return args;
+}
+
+function postLocal(path, body) {
+  return new Promise((resolve, reject) => {
+    const req = request(
+      {
+        host: '127.0.0.1',
+        port: 3002,
+        path,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            resolve({
+              statusCode: res.statusCode || 0,
+              body: data ? JSON.parse(data) : {},
+            });
+          } catch (err) {
+            reject(err);
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+function getLocal(path) {
+  return new Promise((resolve, reject) => {
+    const req = request(
+      { host: '127.0.0.1', port: 3002, path, method: 'GET' },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            resolve({
+              statusCode: res.statusCode || 0,
+              body: data ? JSON.parse(data) : {},
+            });
+          } catch (err) {
+            reject(err);
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0] || 'start';
+
+  if (command === 'start') {
+    await startConnector();
+    return;
+  }
+
+  if (command === 'config-path') {
+    console.log(TICLAWK_CONFIG_PATH);
+    return;
+  }
+
+  if (command === 'health') {
+    const res = await getLocal('/health');
+    console.log(JSON.stringify(res.body, null, 2));
+    process.exitCode = res.statusCode >= 400 ? 1 : 0;
+    return;
+  }
+
+  if (command === 'pair') {
+    if (!args.code) {
+      console.error('--code is required');
+      process.exit(1);
+    }
+
+    const serviceType = args.type === 'openclaw' ? 'openclaw' : 'claude_code';
+    const payload = serviceType === 'openclaw'
+      ? {
+          code: args.code,
+          serviceType,
+          channelId: args['channel-id'],
+          name: args.name || args['channel-id'],
+        }
+      : {
+          code: args.code,
+          sessionId: args['session-id'],
+        };
+
+    if (serviceType === 'openclaw' && !payload.channelId) {
+      console.error('--channel-id is required for openclaw pairing');
+      process.exit(1);
+    }
+    if (serviceType === 'claude_code' && !payload.sessionId) {
+      console.error('--session-id is required for claude_code pairing');
+      process.exit(1);
+    }
+
+    const res = await postLocal('/pair', payload);
+    console.log(JSON.stringify(res.body, null, 2));
+    process.exitCode = res.statusCode >= 400 ? 1 : 0;
+    return;
+  }
+
+  printUsage();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.message || String(err));
+  process.exit(1);
+});

package/cc-watcher.mjs

@@ -0,0 +1,229 @@
+/**
+ * cc-watcher.mjs
+ *
+ * Watches Claude Code sessions for new output and exposes transcript helpers.
+ * Ticlawk connector uses this to discover sessions, sync transcript history,
+ * and detect new transcript entries.
+ */
+
+import { readFileSync, statSync, watch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+// ── Discover Sessions ───────────────────────────────────────────────────
+
+/**
+ * Scan a .claude/projects/ directory for session .jsonl files.
+ * Returns an array of { sessionId, project, path, projectDir }
+ */
+export async function discoverSessions(claudeProjectsDir) {
+  const sessions = [];
+
+  let projectDirs;
+  try {
+    projectDirs = await readdir(claudeProjectsDir);
+  } catch {
+    return sessions;
+  }
+
+  for (const projName of projectDirs) {
+    const projPath = join(claudeProjectsDir, projName);
+
+    let files;
+    try {
+      files = await readdir(projPath);
+    } catch {
+      continue;
+    }
+
+    // Collect all .jsonl sessions in this project, pick the most recent one
+    let best = null;
+    let bestMtime = 0;
+
+    for (const file of files) {
+      if (!file.endsWith('.jsonl')) continue;
+      if (file.includes('subagent')) continue;
+
+      const filePath = join(projPath, file);
+      let mtime = 0;
+      try {
+        mtime = statSync(filePath).mtimeMs;
+      } catch { continue; }
+
+      if (mtime > bestMtime) {
+        bestMtime = mtime;
+        best = { file, filePath };
+      }
+    }
+
+    if (!best) continue;
+
+    const sessionId = basename(best.file, '.jsonl');
+
+    // Read cwd directly from transcript (first user entry has it)
+    let projectDir = null;
+    try {
+      const content = readFileSync(best.filePath, 'utf8');
+      for (const line of content.split('\n')) {
+        if (!line.trim()) continue;
+        const entry = JSON.parse(line);
+        if (entry.cwd) {
+          projectDir = entry.cwd;
+          break;
+        }
+      }
+    } catch { /* ignore */ }
+
+    if (!projectDir) {
+      // Fallback: naive decode
+      projectDir = '/' + projName.replace(/^-/, '').replace(/-/g, '/');
+    }
+
+    sessions.push({
+      sessionId,
+      project: projName,
+      path: best.filePath,
+      projectDir,
+    });
+  }
+
+  return sessions;
+}
+
+// ── Watch Transcript ────────────────────────────────────────────────────
+
+/**
+ * Watch a transcript .jsonl file for new assistant messages.
+ * Calls onMessage(msg) when a new assistant message is detected.
+ * msg = { type: 'assistant', text: string, raw: object }
+ *
+ * Returns a cleanup function to stop watching.
+ */
+export function watchTranscript(transcriptPath, onMessage) {
+  let lastSize = 0;
+
+  try {
+    lastSize = statSync(transcriptPath).size;
+  } catch {
+    // File might not exist yet
+  }
+
+  const checkForNew = () => {
+    let currentSize;
+    try {
+      currentSize = statSync(transcriptPath).size;
+    } catch {
+      return;
+    }
+
+    if (currentSize <= lastSize) return;
+
+    // Read only the new bytes (use Buffer to slice by byte offset, not char offset)
+    const buf = readFileSync(transcriptPath);
+    const newContent = buf.subarray(lastSize).toString('utf8');
+    lastSize = currentSize;
+
+    // Parse new lines
+    const lines = newContent.split('\n').filter(l => l.trim());
+    for (const line of lines) {
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (entry.type !== 'assistant' && entry.type !== 'user') continue;
+
+      // Extract text and tool info from the message content
+      const content = entry.message?.content;
+      let text = '';
+      let toolNames = [];
+      if (typeof content === 'string') {
+        text = content;
+      } else if (Array.isArray(content)) {
+        text = content
+          .filter(c => c.type === 'text')
+          .map(c => c.text)
+          .join('\n');
+        toolNames = content
+          .filter(c => c.type === 'tool_use')
+          .map(c => c.name);
+      }
+
+      const stopReason = entry.message?.stop_reason;
+
+      // Emit tool_use events (agent is processing)
+      if (entry.type === 'assistant' && toolNames.length > 0 && stopReason === 'tool_use') {
+        onMessage({ type: 'tool_use', text: '', toolNames, raw: entry });
+        continue; // Don't also emit as text message
+      }
+
+      if (!text) continue;
+
+      onMessage({ type: entry.type, text, raw: entry });
+    }
+  };
+
+  // Use fs.watch for instant detection, poll as fallback
+  let watcher;
+  try {
+    watcher = watch(transcriptPath, { persistent: false }, () => {
+      checkForNew();
+    });
+  } catch {
+    // fs.watch not available, fall back to polling
+  }
+
+  const interval = setInterval(checkForNew, 2000);
+
+  return () => {
+    clearInterval(interval);
+    watcher?.close();
+  };
+}
+
+// ── Parse Transcript ────────────────────────────────────────────────────
+
+/**
+ * Extract text from a transcript entry's message content.
+ */
+function extractText(entry) {
+  const content = entry.message?.content;
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+  }
+  return '';
+}
+
+/**
+ * Read transcript and return all user/assistant messages.
+ * Each entry: { type: 'user'|'assistant', text: string, timestamp: number }
+ */
+export function readTranscript(transcriptPath) {
+  let content;
+  try {
+    content = readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const messages = [];
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+
+    if (entry.type !== 'user' && entry.type !== 'assistant') continue;
+
+    const text = extractText(entry);
+    if (!text) continue;
+
+    // Use message timestamp if available, otherwise approximate
+    const timestamp = entry.message?.timestamp || entry.timestamp || 0;
+    messages.push({ type: entry.type, text, timestamp });
+  }
+
+  return messages;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ticlawk-connector",
+  "version": "0.1.0-alpha.0",
+  "description": "Local connector for pairing Claude Code and OpenClaw agents with ticlawk.",
+  "type": "module",
+  "main": "ticlawk-connector.mjs",
+  "bin": {
+    "ticlawk-connector": "bin/ticlawk-connector.mjs"
+  },
+  "files": [
+    "bin/",
+    "cc-watcher.mjs",
+    "ticlawk-api.mjs",
+    "ticlawk-connector.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node ./bin/ticlawk-connector.mjs start",
+    "connector": "node ./bin/ticlawk-connector.mjs start",
+    "health": "node ./bin/ticlawk-connector.mjs health",
+    "dev": "echo 'Configure ~/.ticlawk/.config, then: npm run connector'",
+    "generate:setup-docs": "node scripts/generate-setup-docs.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darthjaja6/ticlawk.git"
+  },
+  "keywords": [
+    "ticlawk",
+    "connector",
+    "claude-code",
+    "openclaw",
+    "agent"
+  ],
+  "author": "ticlawk",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/darthjaja6/ticlawk/issues"
+  },
+  "homepage": "https://github.com/darthjaja6/ticlawk#readme",
+  "dependencies": {
+    "@supabase/supabase-js": "^2.99.2",
+    "openclaw": "^2026.3.13",
+    "ws": "^8.19.0"
+  }
+}

package/ticlawk-api.mjs

@@ -0,0 +1,128 @@
+/**
+ * ticlawk-api.mjs
+ *
+ * HTTP API client for ticlawk-connector.
+ * All operations go through ticlawk.com/api/* (or TICLAWK_API_URL).
+ * No direct Supabase access — only needs a tk_ API key.
+ */
+
+function getApiUrl() { return process.env.TICLAWK_API_URL || 'https://ticlawk.com'; }
+function getApiKey() { return process.env.TICLAWK_API_KEY || ''; }
+
+async function apiFetch(path, opts = {}) {
+  const url = `${getApiUrl()}${path}`;
+  const res = await fetch(url, {
+    ...opts,
+    headers: {
+      'Authorization': `Bearer ${getApiKey()}`,
+      ...(opts.body && !(opts.body instanceof FormData) ? {'Content-Type': 'application/json'} : {}),
+      ...opts.headers,
+    },
+    signal: AbortSignal.timeout(opts.timeout || 15000),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    let msg;
+    try { msg = JSON.parse(text).error; } catch { msg = text; }
+    throw new Error(`API ${res.status}: ${msg || res.statusText}`);
+  }
+
+  return res.json();
+}
+
+// ── Channels ──
+
+export async function getChannels() {
+  const { data } = await apiFetch('/api/channels');
+  return data || [];
+}
+
+export async function getChannel(id) {
+  const { data } = await apiFetch(`/api/channels/${id}`);
+  return data;
+}
+
+export async function updateChannel(id, updates) {
+  return apiFetch(`/api/channels/${id}`, {
+    method: 'PATCH',
+    body: JSON.stringify(updates),
+  });
+}
+
+// ── Messages ──
+
+export async function getPendingMessages() {
+  const { data } = await apiFetch('/api/messages/pending');
+  return data || [];
+}
+
+export async function insertMessage(row) {
+  const { data } = await apiFetch('/api/messages', {
+    method: 'POST',
+    body: JSON.stringify(row),
+  });
+  return data;
+}
+
+export async function syncMessages(rows) {
+  return apiFetch('/api/messages/sync', {
+    method: 'POST',
+    body: JSON.stringify({ rows }),
+  });
+}
+
+export async function updateMessage(id, updates) {
+  return apiFetch(`/api/messages/${id}`, {
+    method: 'PATCH',
+    body: JSON.stringify(updates),
+  });
+}
+
+// ── Cards ──
+
+export async function insertCard(row) {
+  const { data } = await apiFetch('/api/cards', {
+    method: 'POST',
+    body: JSON.stringify(row),
+  });
+  return data;
+}
+
+// ── Upload ──
+
+export async function uploadFile(filePath, fileData, contentType) {
+  const formData = new FormData();
+  formData.append('file', new Blob([fileData], { type: contentType }), filePath);
+  formData.append('path', filePath);
+  formData.append('contentType', contentType);
+
+  const { url } = await apiFetch('/api/upload', {
+    method: 'POST',
+    body: formData,
+    timeout: 30000,
+  });
+  return url;
+}
+
+// ── Dispatch (existing endpoint) ──
+
+export async function dispatch(event) {
+  return apiFetch('/dispatch', {
+    method: 'POST',
+    body: JSON.stringify(event),
+  });
+}
+
+// ── Pair (no auth needed) ──
+
+export async function pair(payload) {
+  const url = `${getApiUrl()}/dispatch`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'pair', ...payload }),
+    signal: AbortSignal.timeout(15000),
+  });
+  return res.json();
+}