@controlflow-ai/daemon 0.1.0

package/src/failure-message.ts

@@ -0,0 +1,17 @@
+import type { LockClient } from './client.js';
+import type { Message } from './types.js';
+
+export async function writeFailureMessage(client: LockClient, message: Message, agent: string, output: string): Promise<void> {
+  const content = `daemon failed to run ${agent}:\n${output}`;
+  const parentId = message.parent_id ?? message.id;
+  const idempotencyKey = `delivery:${message.id}:failure-system-message`;
+
+  await client.sendMessage({
+    chat: message.chat_name,
+    parent_id: parentId,
+    sender: agent,
+    content,
+    type: 'system',
+    idempotency_key: idempotencyKey,
+  });
+}

package/src/format.ts

@@ -0,0 +1,13 @@
+import type { Message } from './types.js';
+import { sanitizeProviderIds } from './provider-identity.js';
+
+export function formatMessage(message: Message): string {
+  const chatName = sanitizeProviderIds(message.chat_name);
+  const target = message.parent_id === null ? `#${chatName}` : `#${chatName}:${message.parent_id}`;
+  const to = message.recipient ? ` -> @${sanitizeProviderIds(message.recipient)}` : '';
+  return `[${message.id} ${target} ${message.created_at}] @${sanitizeProviderIds(message.sender)}${to}: ${sanitizeProviderIds(message.content)}`;
+}
+
+export function formatMessages(messages: Message[]): string {
+  return messages.map(formatMessage).join('\n');
+}

package/src/http.ts

@@ -0,0 +1,55 @@
+import type { ApiResponse } from './types.js';
+
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export async function readJson<T extends object>(request: Request): Promise<T> {
+  try {
+    const value = await request.json();
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new HttpError(400, 'BAD_JSON', 'expected a JSON object');
+    }
+    return value as T;
+  } catch (error) {
+    if (error instanceof HttpError) throw error;
+    throw new HttpError(400, 'BAD_JSON', 'request body must be valid JSON');
+  }
+}
+
+export function json<T>(data: T, status = 200): Response {
+  const body: ApiResponse<T> = { ok: true, data };
+  return Response.json(body, { status });
+}
+
+export function failure(error: unknown): Response {
+  if (error instanceof HttpError) {
+    return Response.json({ ok: false, code: error.code, message: error.message }, { status: error.status });
+  }
+
+  if (error instanceof Error) {
+    return Response.json({ ok: false, code: 'ERROR', message: error.message }, { status: 400 });
+  }
+
+  return Response.json({ ok: false, code: 'ERROR', message: 'unknown error' }, { status: 500 });
+}
+
+export function numberParam(url: URL, name: string, fallback?: number): number | undefined {
+  const value = url.searchParams.get(name);
+  if (value === null || value === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new HttpError(400, 'BAD_PARAM', `${name} must be a number`);
+  return parsed;
+}
+
+export function stringParam(url: URL, name: string): string | undefined {
+  const value = url.searchParams.get(name);
+  return value === null || value === '' ? undefined : value;
+}

package/src/lark/agent-runtime.ts

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+
+export interface AgentInvocation {
+  /** Chat-scoped identifier so the runtime can keep per-chat state if desired. */
+  chatKey: string;
+  /** Most-recent batch of messages to feed to the agent. */
+  messages: Array<{
+    senderOpenId: string;
+    text: string;
+    larkMessageId: string;
+    lockMessageId: number;
+    parentLockMessageId: number | null;
+  }>;
+  /** True when the agent was idle and this is the first batch in a new run. */
+  isFresh: boolean;
+  /** When true, this batch is a re-delivery after a kill/restart; runtime
+   *  may want to log it or adjust prompt framing. */
+  isRedelivery?: boolean;
+  /** Abort signal: when the dispatcher kills a run, this signal is fired.
+   *  Runtimes that respect it should bail out promptly and reject the
+   *  promise (any error works). */
+  signal?: AbortSignal;
+}
+
+export interface AgentReply {
+  /** Plain text to post back to the chat. Empty string suppresses any send. */
+  text: string;
+  /** Optional structured metadata for logging / future routing. */
+  meta?: Record<string, unknown>;
+}
+
+export interface AgentRuntime {
+  readonly name: string;
+  run(invocation: AgentInvocation): Promise<AgentReply>;
+}
+
+/** Trivial runtime: echoes back the concatenated text with an agent prefix. */
+export function makeEchoRuntime(prefix = 'echo'): AgentRuntime {
+  return {
+    name: `echo:${prefix}`,
+    async run(invocation): Promise<AgentReply> {
+      const joined = invocation.messages.map((m) => m.text).join('\n');
+      return { text: `[${prefix}] ${joined}` };
+    },
+  };
+}
+
+/**
+ * Shell runtime: spawns the given command, pipes invocation JSON to stdin,
+ * captures stdout, returns it as the agent reply. The command is interpreted
+ * via /bin/sh -c so the caller can use pipelines / args freely (M3 keeps it
+ * simple; a future M4 can add per-arg parsing or env injection).
+ */
+export interface ShellRuntimeOptions {
+  command: string;
+  cwd?: string;
+  timeoutMs?: number;
+  env?: Record<string, string>;
+}
+
+export function makeShellRuntime(options: ShellRuntimeOptions): AgentRuntime {
+  const cmd = options.command.trim();
+  if (!cmd) throw new Error('shell runtime requires a non-empty command');
+  return {
+    name: `shell:${cmd}`,
+    async run(invocation): Promise<AgentReply> {
+      return await new Promise<AgentReply>((resolve, reject) => {
+        const child = spawn('/bin/sh', ['-c', cmd], {
+          cwd: options.cwd,
+          env: { ...process.env, ...(options.env ?? {}) },
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const stdoutChunks: Buffer[] = [];
+        const stderrChunks: Buffer[] = [];
+        let settled = false;
+        const timer = options.timeoutMs
+          ? setTimeout(() => {
+              if (settled) return;
+              settled = true;
+              child.kill('SIGTERM');
+              reject(new Error(`shell runtime timeout after ${options.timeoutMs}ms`));
+            }, options.timeoutMs)
+          : null;
+        const onAbort = (): void => {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          try {
+            child.kill('SIGTERM');
+          } catch {
+            /* ignore */
+          }
+          reject(new Error('aborted'));
+        };
+        if (invocation.signal) {
+          if (invocation.signal.aborted) {
+            onAbort();
+            return;
+          }
+          invocation.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+        child.on('error', (err) => {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          reject(err);
+        });
+        child.on('close', (code) => {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          if (code !== 0) {
+            const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+            reject(new Error(`shell runtime exited ${code}${stderr ? `: ${stderr}` : ''}`));
+            return;
+          }
+          const stdout = Buffer.concat(stdoutChunks).toString('utf8').trim();
+          resolve({ text: stdout, meta: { exitCode: code } });
+        });
+        try {
+          child.stdin.end(JSON.stringify(invocation));
+        } catch (err) {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          reject(err);
+        }
+      });
+    },
+  };
+}
+
+/** Convenience parser: "echo", "echo:bot", "shell:bun -e 'console.log(\"hi\")'". */
+export function parseRuntimeSpec(spec: string): AgentRuntime {
+  const trimmed = spec.trim();
+  if (!trimmed || trimmed === 'echo') return makeEchoRuntime();
+  if (trimmed.startsWith('echo:')) return makeEchoRuntime(trimmed.slice('echo:'.length));
+  if (trimmed.startsWith('shell:')) return makeShellRuntime({ command: trimmed.slice('shell:'.length) });
+  throw new Error(`unknown agent runtime spec: ${spec}`);
+}