ticlawk 0.1.12-dev.0

package/src/adapters/ticlawk/api.mjs

@@ -0,0 +1,360 @@
+/**
+ * ticlawk adapter — HTTP API client.
+ *
+ * Thin wrapper around `ticlawk.com/api/*` (override with `TICLAWK_API_URL`).
+ * Only depends on a `tk_` connector bearer API key from
+ * `process.env.TICLAWK_CONNECTOR_API_KEY`.
+ * No direct Supabase access.
+ */
+
+import { loadPersistentConfig, TICLAWK_CONNECTOR_WS_URL } from '../../core/config.mjs';
+import { debugError, debugLog } from '../../core/logger.mjs';
+import { readPkgVersion } from '../../core/update.mjs';
+
+const DEFAULT_CONNECTOR_WS_URL = 'wss://edge.ticlawk.com/functions/v1/connector-wake';
+
+export function getApiUrl() {
+  const config = loadPersistentConfig();
+  return process.env.TICLAWK_API_URL || config.TICLAWK_API_URL || 'https://ticlawk.com';
+}
+
+export function getApiKey() {
+  const config = loadPersistentConfig();
+  return process.env.TICLAWK_CONNECTOR_API_KEY || config.TICLAWK_CONNECTOR_API_KEY || '';
+}
+
+export function getConnectorWsUrl() {
+  const config = loadPersistentConfig();
+  const configured = process.env[TICLAWK_CONNECTOR_WS_URL] || config[TICLAWK_CONNECTOR_WS_URL];
+  if (configured) return configured;
+  return DEFAULT_CONNECTOR_WS_URL;
+}
+
+// Agent event writes must preserve per-agent order while still allowing
+// different agents to proceed concurrently.
+const agentEventQueues = new Map(); // agentId -> Promise
+
+export class AgentFreewayUpdateRequiredError extends Error {
+  constructor(payload = {}) {
+    const currentVersion = payload.current_agent_freeway_version || payload.currentAgentFreewayVersion || getAgentFreewayVersion();
+    const requiredVersion = payload.required_agent_freeway_version || payload.requiredAgentFreewayVersion || '';
+    super(`Ticlawk requires ticlawk >= ${requiredVersion || 'unknown'}, current version is ${currentVersion || 'unknown'}. Please update ticlawk.`);
+    this.name = 'AgentFreewayUpdateRequiredError';
+    this.code = 'agent_freeway_update_required';
+    this.updateRequired = true;
+    this.status = 409;
+    this.statusCode = 409;
+    this.currentAgentFreewayVersion = currentVersion || null;
+    this.requiredAgentFreewayVersion = requiredVersion || null;
+    this.payload = payload;
+  }
+}
+
+export function isUpdateRequiredError(err) {
+  return Boolean(err?.updateRequired || err?.code === 'agent_freeway_update_required');
+}
+
+export function getAgentFreewayVersion() {
+  return readPkgVersion() || '0.0.0';
+}
+
+function withAgentFreewayVersion(body = {}) {
+  return {
+    ...body,
+    agent_freeway_version: getAgentFreewayVersion(),
+  };
+}
+
+function isUpdateRequiredPayload(payload) {
+  return Boolean(
+    payload?.error === 'agent_freeway_update_required'
+    || payload?.code === 'agent_freeway_update_required'
+  );
+}
+
+function shortId(value) {
+  return value ? String(value).slice(0, 8) : null;
+}
+
+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),
+  });
+
+  const text = await res.text().catch(() => '');
+  let parsed = {};
+  if (text) {
+    try { parsed = JSON.parse(text); } catch { parsed = null; }
+  }
+
+  if (isUpdateRequiredPayload(parsed)) {
+    throw new AgentFreewayUpdateRequiredError(parsed);
+  }
+
+  if (!res.ok) {
+    const msg = parsed?.error || parsed?.message || text;
+    const err = new Error(`API ${res.status}: ${msg || res.statusText}`);
+    err.status = res.status;
+    err.statusCode = res.status;
+    if (parsed?.error) err.code = parsed.error;
+    if (parsed?.code) err.code = parsed.code;
+    err.payload = parsed || {};
+    throw err;
+  }
+
+  return parsed || {};
+}
+
+// ── Agents ──
+
+export async function getAgents({ hostId } = {}) {
+  const query = hostId ? `?${new URLSearchParams({ runtime_host_id: hostId })}` : '';
+  const { data } = await apiFetch(`/api/agents${query}`);
+  if (!Array.isArray(data)) {
+    const err = new Error('API /api/agents response missing data array');
+    err.code = 'invalid_agents_response';
+    throw err;
+  }
+  return data;
+}
+
+export async function getChannels(hostId = null) {
+  return getAgents({ hostId });
+}
+
+export async function getAgent(id) {
+  const { data } = await apiFetch(`/api/agents/${id}`);
+  return data;
+}
+
+export async function getChannel(id) {
+  return getAgent(id);
+}
+
+export async function updateAgent(id, updates) {
+  return apiFetch(`/api/agents/${id}`, {
+    method: 'PATCH',
+    body: JSON.stringify(updates),
+  });
+}
+
+export async function updateChannel(id, updates) {
+  return updateAgent(id, updates);
+}
+
+export async function postRuntimeResult(body) {
+  const result = await apiFetch('/api/runtime-results', {
+    method: 'POST',
+    body: JSON.stringify(body),
+    timeout: 30000,
+  });
+  if (result?.matched === false) {
+    throw new Error('runtime result was not matched');
+  }
+  return result;
+}
+
+// ── Messages ──
+
+export async function getPendingMessages() {
+  const { data } = await apiFetch('/api/messages/pending');
+  return data || [];
+}
+
+export async function claimPendingMessages(hostId, limit = 5, excludedAgentIds = []) {
+  const { data } = await apiFetch('/api/messages/claim-pending', {
+    method: 'POST',
+    body: JSON.stringify(withAgentFreewayVersion({
+      runtime_host_id: hostId,
+      limit,
+      excluded_agent_ids: excludedAgentIds,
+    })),
+  });
+  return data || [];
+}
+
+export async function syncMessages(rows) {
+  return apiFetch('/api/messages/sync', {
+    method: 'POST',
+    body: JSON.stringify({ rows }),
+  });
+}
+
+export async function claimMessage(id, hostId) {
+  return apiFetch(`/api/messages/${id}/claim`, {
+    method: 'POST',
+    body: JSON.stringify(withAgentFreewayVersion({ runtime_host_id: hostId })),
+  });
+}
+
+export async function releaseMessage(id, hostId) {
+  return apiFetch(`/api/messages/${id}/release`, {
+    method: 'POST',
+    body: JSON.stringify({ runtime_host_id: hostId }),
+  });
+}
+
+export async function completeMessage(id, hostId) {
+  return apiFetch(`/api/messages/${id}/complete`, {
+    method: 'POST',
+    body: JSON.stringify({ runtime_host_id: hostId }),
+  });
+}
+
+export async function recoverClaimedMessages(hostId) {
+  return apiFetch('/api/messages/recover', {
+    method: 'POST',
+    body: JSON.stringify(withAgentFreewayVersion({ runtime_host_id: hostId })),
+  });
+}
+
+// ── Upload ──
+
+export async function uploadAsset(fileName, fileData, contentType, kind = 'chat_media') {
+  const formData = new FormData();
+  formData.append('file', new Blob([fileData], { type: contentType }), fileName);
+  formData.append('kind', kind);
+  if (contentType) formData.append('content_type', contentType);
+
+  const { data } = await apiFetch('/api/assets/upload', {
+    method: 'POST',
+    body: formData,
+    timeout: 30000,
+  });
+  return data;
+}
+
+// ── Channel event pipe ──
+
+export async function postEvent({ agent, agent_id, runtime_host_id, session_id, cwd, runtime_version, event, required = false }) {
+  const agentId = agent_id || null;
+  const queueKey = agentId || `${agent}:${session_id || ''}`;
+  const previous = agentEventQueues.get(queueKey) || Promise.resolve(null);
+  const eventName = event?.worker_event_name || event?.hook_event_name || event?.event_name || 'unknown';
+  const turnId = event?.turn_id || event?.reply_to_message_id || null;
+  const seq = event?.event_seq ?? null;
+  const deltaChars = typeof event?.delta === 'string' ? event.delta.length : null;
+
+  const queued = previous
+    .catch(() => null)
+    .then(async () => {
+      const startedAt = Date.now();
+      try {
+        const result = await apiFetch('/api/events', {
+          method: 'POST',
+          body: JSON.stringify({ agent, agent_id: agentId, runtime_host_id, session_id, cwd, runtime_version, event }),
+          timeout: 5000,
+        });
+        if (required && result?.matched === false) {
+          throw new Error(`event was not matched (${eventName})`);
+        }
+        debugLog('events', 'post.ok', {
+          agent,
+          agentId,
+          sessionId: shortId(session_id),
+          runtimeVersion: runtime_version ?? null,
+          turnId: shortId(turnId),
+          eventName,
+          seq,
+          deltaChars,
+          durationMs: Date.now() - startedAt,
+        });
+        return result;
+      } catch (err) {
+        debugError('events', 'post.failed', {
+          agent,
+          agentId,
+          sessionId: shortId(session_id),
+          runtimeVersion: runtime_version ?? null,
+          turnId: shortId(turnId),
+          eventName,
+          seq,
+          deltaChars,
+          durationMs: Date.now() - startedAt,
+          error: err?.message || 'unknown error',
+        });
+        if (required) {
+          throw err;
+        }
+        // Best-effort by default. Callers that need a hard failure set
+        // `required: true` (used for the final reply path).
+        return null;
+      }
+    });
+
+  agentEventQueues.set(queueKey, queued);
+  queued.finally(() => {
+    if (agentEventQueues.get(queueKey) === queued) {
+      agentEventQueues.delete(queueKey);
+    }
+  });
+
+  return queued;
+}
+
+// ── 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),
+  });
+  const body = await res.json().catch(() => ({}));
+  return {
+    statusCode: res.status,
+    ...body,
+  };
+}
+
+export async function pairPreview(payload) {
+  const url = `${getApiUrl()}/dispatch`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'pair-preview', ...payload }),
+    signal: AbortSignal.timeout(15000),
+  });
+  return res.json();
+}
+
+async function pairingRequest(payload, timeout = 15000) {
+  const url = `${getApiUrl()}/api/agent-pairings`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(timeout),
+  });
+  const body = await res.json().catch(() => ({}));
+  return {
+    statusCode: res.status,
+    ...body,
+  };
+}
+
+export async function createPairingSession(payload) {
+  return pairingRequest({ action: 'create', ...payload });
+}
+
+export async function pollPairingSession(payload) {
+  return pairingRequest({ action: 'poll', ...payload }, 30000);
+}
+
+export async function cancelPairingSession(payload) {
+  return pairingRequest({ action: 'cancel', ...payload }).catch(() => null);
+}
+
+export async function getMe() {
+  const { data } = await apiFetch('/api/me');
+  return data || null;
+}

package/src/adapters/ticlawk/cards.mjs

@@ -0,0 +1,149 @@
+/**
+ * ticlawk adapter — final agent message / media write path.
+ *
+ * Everything here turns an agent result (text + optional media local paths)
+ * into a terminal runtime result written back to ticlawk.
+ *
+ * This module imports from `./api.mjs` (HTTP client) and from
+ * `../../core/logger.mjs` (structured logging). No runtime dependencies.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import * as api from './api.mjs';
+import { extractMediaPaths } from '../../core/media/outbound.mjs';
+import { debugLog, debugError } from '../../core/logger.mjs';
+import { TICLAWK_CONNECTOR_API_KEY } from '../../core/config.mjs';
+
+const MIME_MAP = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+  '.mp4': 'video/mp4', '.webm': 'video/webm',
+  '.opus': 'audio/opus', '.mp3': 'audio/mpeg', '.wav': 'audio/wav',
+  '.pdf': 'application/pdf',
+};
+
+async function uploadLocalAsset(localPath) {
+  if (!process.env[TICLAWK_CONNECTOR_API_KEY]) {
+    debugError('relay', 'upload.skipped', {
+      localPath,
+      reason: 'missing connector api key',
+    });
+    return null;
+  }
+  if (!existsSync(localPath)) {
+    debugError('relay', 'upload.skipped', {
+      localPath,
+      reason: 'file not found',
+    });
+    return null;
+  }
+
+  const ext = extname(localPath).toLowerCase();
+  const contentType = MIME_MAP[ext] || 'application/octet-stream';
+  const fileName = `${Date.now()}-${randomUUID().slice(0, 8)}${ext}`;
+  const fileData = readFileSync(localPath);
+
+  try {
+    const asset = await api.uploadAsset(fileName, fileData, contentType);
+    if (!asset?.asset_id) {
+      debugError('relay', 'upload.failed', {
+        localPath,
+        fileName,
+        error: 'missing asset_id in upload response',
+      });
+      return null;
+    }
+    debugLog('relay', 'upload.ok', {
+      localPath,
+      fileName,
+      assetId: asset.asset_id,
+      contentType: asset.content_type || contentType,
+      sizeBytes: asset.size_bytes ?? null,
+    });
+    return asset;
+  } catch (err) {
+    debugError('relay', 'upload.failed', {
+      localPath,
+      fileName,
+      error: err.message,
+    });
+    return null;
+  }
+}
+
+export async function uploadMediaAssets(localPaths) {
+  const assets = [];
+  for (const p of localPaths) {
+    const asset = await uploadLocalAsset(p);
+    if (asset) assets.push(asset);
+  }
+  return assets;
+}
+
+export async function processAndSaveResult(result, opts) {
+  const { agentId: explicitAgentId, sessionKey, hostId, type, replyToMessageId, agent, sessionId, turnId, runtimeVersion } = opts;
+  const agentId = explicitAgentId || sessionKey;
+  const startedAt = Date.now();
+
+  // Collect media: from agent mediaUrls + parsed from text
+  const allLocalPaths = [...new Set([
+    ...(result.mediaUrls || []),
+    ...extractMediaPaths(result.text || ''),
+  ])];
+
+  debugLog('relay', 'process-result.begin', {
+    agentId,
+    type,
+    parentMessageId: replyToMessageId || null,
+    textLength: result.text?.length || 0,
+    localMediaCount: allLocalPaths.length,
+  });
+
+  // Upload local media to Ticlawk private chat assets.
+  const uploadedAssets = await uploadMediaAssets(allLocalPaths);
+  const uploadedAssetIds = uploadedAssets
+    .map((asset) => asset?.asset_id)
+    .filter(Boolean);
+
+  const updateId = randomUUID();
+  debugLog('relay', 'post-final.begin', {
+    agentId,
+    updateId,
+    durationMs: Date.now() - startedAt,
+    uploadedMediaCount: uploadedAssetIds.length,
+  });
+  try {
+    await api.postRuntimeResult({
+      agent,
+      agent_id: agentId,
+      runtime_host_id: hostId,
+      session_id: sessionId || null,
+      cwd: '',
+      runtime_version: runtimeVersion ?? null,
+      result_id: updateId,
+      turn_id: turnId || replyToMessageId || null,
+      reply_to_message_id: replyToMessageId || null,
+      origin_ts: new Date().toISOString(),
+      text: result.text || '',
+      media_asset_ids: uploadedAssetIds,
+      output_type: type || 'agent_message',
+    });
+  } catch (err) {
+    debugError('relay', 'post-final.failed', {
+      agentId,
+      updateId,
+      durationMs: Date.now() - startedAt,
+      error: err.message,
+    });
+    throw err;
+  }
+  debugLog('relay', 'process-result.ok', {
+    agentId,
+    updateId,
+    durationMs: Date.now() - startedAt,
+    uploadedMediaCount: uploadedAssetIds.length,
+  });
+  return { id: updateId, agentId };
+}

package/src/adapters/ticlawk/credentials.mjs

@@ -0,0 +1,25 @@
+/**
+ * ticlawk adapter — API key persistence.
+ *
+ * The ticlawk connect flow returns a `tk_...` bearer key in response to
+ * a local adapter connect call. We persist it to `~/.ticlawk/.config`
+ * using the connector-specific env name so publisher scripts can keep using
+ * `TICLAWK_API_KEY` without being polluted by ticlawk.
+ */
+
+import { AF_ADAPTER_KEY, AF_CONFIG_PATH, LEGACY_TICLAWK_API_KEY, persistConfig, TICLAWK_CONNECTOR_API_KEY } from '../../core/config.mjs';
+
+export function persistApiCredential(apiKey) {
+  if (!apiKey || !apiKey.startsWith('tk_')) return;
+
+  persistConfig({
+    [AF_ADAPTER_KEY]: 'ticlawk',
+    [TICLAWK_CONNECTOR_API_KEY]: apiKey,
+    [LEGACY_TICLAWK_API_KEY]: '',
+    TICLAWK_SETUP_CODE: '',
+  });
+  process.env[TICLAWK_CONNECTOR_API_KEY] = apiKey;
+  delete process.env[LEGACY_TICLAWK_API_KEY];
+  delete process.env.TICLAWK_SETUP_CODE;
+  console.log(`[connect] saved ${TICLAWK_CONNECTOR_API_KEY} to ${AF_CONFIG_PATH}`);
+}