clawless 0.1.2

package/TESTING.md

@@ -0,0 +1,239 @@
+# Scheduler API Manual Testing Guide
+
+This guide walks through manual testing of the scheduler API functionality.
+
+## Prerequisites
+
+1. The bridge must be running with a valid Telegram bot token
+2. You must have sent at least one message to the bot to establish a chat binding
+3. `curl` and `jq` must be installed for the test commands
+
+## Test Setup
+
+1. Start the bridge in development mode:
+```bash
+npm run dev
+```
+
+2. In another terminal, verify the server is running:
+```bash
+curl http://127.0.0.1:8788/healthz
+# Expected: {"ok":true}
+```
+
+## Test Cases
+
+### Test 1: Create a Recurring Schedule
+
+Create a schedule that runs every minute:
+
+```bash
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "What is the current time?",
+    "description": "Test recurring - every minute",
+    "cronExpression": "* * * * *"
+  }' | jq .
+```
+
+**Expected Result:**
+- HTTP 201 response
+- JSON with `ok: true` and schedule details including an `id`
+
+**Save the schedule ID** from the response for later tests.
+
+### Test 2: List All Schedules
+
+```bash
+curl http://127.0.0.1:8788/api/schedule | jq .
+```
+
+**Expected Result:**
+- HTTP 200 response
+- JSON array containing the schedule from Test 1
+
+### Test 3: Get a Specific Schedule
+
+Replace `SCHEDULE_ID` with the ID from Test 1:
+
+```bash
+curl http://127.0.0.1:8788/api/schedule/SCHEDULE_ID | jq .
+```
+
+**Expected Result:**
+- HTTP 200 response
+- JSON with the schedule details
+
+### Test 4: Wait for Schedule Execution
+
+Wait for 60-65 seconds and observe:
+
+1. Check the bridge logs for:
+   ```
+   [timestamp] Executing scheduled job { scheduleId: '...', message: '...' }
+   ```
+
+2. Check your Telegram chat for a message like:
+   ```
+   🔔 Scheduled task completed:
+
+   Test recurring - every minute
+
+   [Gemini's response about the current time]
+   ```
+
+### Test 5: Create a One-Time Schedule
+
+Create a schedule that runs in 30 seconds:
+
+```bash
+# Generate a timestamp 30 seconds from now
+RUN_AT=$(date -u -d "+30 seconds" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v+30S +"%Y-%m-%dT%H:%M:%SZ")
+
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"message\": \"This is a one-time test message\",
+    \"description\": \"Test one-time schedule\",
+    \"oneTime\": true,
+    \"runAt\": \"${RUN_AT}\"
+  }" | jq .
+```
+
+**Expected Result:**
+- HTTP 201 response
+- Schedule created with `oneTime: true` and `runAt` timestamp
+
+Wait 30+ seconds and verify:
+1. The message appears in Telegram
+2. The schedule is automatically removed (verify with List API)
+
+### Test 6: Test Invalid Cron Expression
+
+```bash
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Test",
+    "cronExpression": "invalid cron"
+  }' | jq .
+```
+
+**Expected Result:**
+- HTTP 400 response
+- Error message about invalid cron expression
+
+### Test 7: Test Missing Required Fields
+
+```bash
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -d '{}' | jq .
+```
+
+**Expected Result:**
+- HTTP 400 response
+- Error message about missing `message` field
+
+### Test 8: Delete a Schedule
+
+Replace `SCHEDULE_ID` with the ID from Test 1:
+
+```bash
+curl -X DELETE http://127.0.0.1:8788/api/schedule/SCHEDULE_ID | jq .
+```
+
+**Expected Result:**
+- HTTP 200 response
+- JSON with `ok: true` and message "Schedule removed"
+
+Verify deletion by listing schedules - the deleted schedule should not appear.
+
+### Test 9: Test with Gemini CLI Integration
+
+Send a message to your Telegram bot:
+
+```
+Create a schedule to check the weather every day at 8am
+```
+
+**Expected Behavior:**
+1. Gemini should parse your request
+2. Call the scheduler API to create a recurring schedule
+3. Respond with confirmation of the schedule creation
+
+Then ask:
+```
+What schedules do I have?
+```
+
+**Expected Behavior:**
+1. Gemini should query the scheduler API
+2. List all active schedules
+3. Show details in a human-readable format
+
+Finally:
+```
+Cancel the weather check schedule
+```
+
+**Expected Behavior:**
+1. Gemini should identify the schedule to delete
+2. Call the DELETE endpoint
+3. Confirm the schedule was removed
+
+## Test with Authentication (Optional)
+
+If `CALLBACK_AUTH_TOKEN` is set in your configuration:
+
+```bash
+# This should fail with 401 Unauthorized
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "Test",
+    "cronExpression": "0 9 * * *"
+  }' | jq .
+
+# This should succeed
+curl -X POST http://127.0.0.1:8788/api/schedule \
+  -H "Content-Type: application/json" \
+  -H "x-callback-token: YOUR_TOKEN_HERE" \
+  -d '{
+    "message": "Test",
+    "cronExpression": "0 9 * * *"
+  }' | jq .
+```
+
+## Cleanup
+
+After testing, remove all test schedules:
+
+```bash
+# List all schedules
+curl http://127.0.0.1:8788/api/schedule | jq -r '.schedules[].id' | while read id; do
+  echo "Deleting schedule: $id"
+  curl -X DELETE http://127.0.0.1:8788/api/schedule/$id
+done
+```
+
+## Common Issues
+
+### Schedule not executing
+- Verify the bridge is still running
+- Check bridge logs for errors
+- Ensure Telegram chat binding is established (send a message to bot first)
+
+### 404 Not Found
+- Verify the callback server is running on port 8788
+- Check if another process is using the port
+
+### No response in Telegram
+- Ensure you've sent at least one message to the bot
+- Check if `lastIncomingChatId` is logged in the bridge output
+- Verify Gemini CLI is properly installed and configured
+
+### Timezone issues
+- Set the `TZ` environment variable to your timezone
+- Example: `TZ=America/New_York npm run dev`

package/acp/clientHelpers.ts

@@ -0,0 +1,23 @@
+export function buildPermissionResponse(options: any[], permissionStrategy: string) {
+  if (!Array.isArray(options) || options.length === 0) {
+    return { outcome: { outcome: 'cancelled' } };
+  }
+
+  if (permissionStrategy === 'cancelled') {
+    return { outcome: { outcome: 'cancelled' } };
+  }
+
+  const preferred = options.find((option: any) => option.kind === permissionStrategy);
+  const selectedOption = preferred || options[0];
+
+  return {
+    outcome: {
+      outcome: 'selected',
+      optionId: selectedOption.optionId,
+    },
+  };
+}
+
+export async function noOpAcpFileOperation(_params: any) {
+  return {};
+}

package/acp/tempAcpRunner.ts

@@ -0,0 +1,320 @@
+import { spawn } from 'node:child_process';
+import { Readable, Writable } from 'node:stream';
+import * as acp from '@agentclientprotocol/sdk';
+import { buildPermissionResponse, noOpAcpFileOperation } from './clientHelpers.js';
+import { getErrorMessage } from '../utils/error.js';
+
+const ACP_DEBUG_STREAM = String(process.env.ACP_DEBUG_STREAM || '').toLowerCase() === 'true';
+const GEMINI_KILL_GRACE_MS = parseInt(process.env.GEMINI_KILL_GRACE_MS || '5000', 10);
+
+export interface TempAcpRunnerOptions {
+  scheduleId: string;
+  promptForGemini: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  timeoutMs: number;
+  noOutputTimeoutMs: number;
+  permissionStrategy: string;
+  stderrTailMaxChars?: number;
+  logInfo: (message: string, details?: unknown) => void;
+}
+
+export async function runPromptWithTempAcp(options: TempAcpRunnerOptions): Promise<string> {
+  const {
+    scheduleId,
+    promptForGemini,
+    command,
+    args,
+    cwd,
+    timeoutMs,
+    noOutputTimeoutMs,
+    permissionStrategy,
+    stderrTailMaxChars = 4000,
+    logInfo,
+  } = options;
+
+  const tempProcess = spawn(command, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    cwd,
+  });
+
+  logInfo('Scheduler temp Gemini ACP process started', {
+    scheduleId,
+    pid: tempProcess.pid,
+    command,
+    args,
+  });
+
+  let tempConnection: any = null;
+  let tempSessionId: string | null = null;
+  let tempCollector: { onActivity: () => void; append: (chunk: string) => void } | null = null;
+  let tempStderrTail = '';
+  let noOutputTimeout: NodeJS.Timeout | null = null;
+  let overallTimeout: NodeJS.Timeout | null = null;
+  let cleanedUp = false;
+
+  const terminateProcessGracefully = () => {
+    return new Promise<void>((resolve) => {
+      if (!tempProcess || tempProcess.killed || tempProcess.exitCode !== null) {
+        resolve();
+        return;
+      }
+
+      let settled = false;
+
+      const finalize = (reason: string) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        logInfo('Scheduler temp Gemini process termination finalized', {
+          scheduleId,
+          pid: tempProcess.pid,
+          reason,
+        });
+        resolve();
+      };
+
+      tempProcess.once('exit', () => finalize('exit'));
+
+      logInfo('Scheduler temp Gemini process SIGTERM', {
+        scheduleId,
+        pid: tempProcess.pid,
+        graceMs: GEMINI_KILL_GRACE_MS,
+      });
+      tempProcess.kill('SIGTERM');
+
+      setTimeout(() => {
+        if (settled || tempProcess.killed || tempProcess.exitCode !== null) {
+          finalize('already-exited');
+          return;
+        }
+
+        logInfo('Scheduler temp Gemini process SIGKILL escalation', {
+          scheduleId,
+          pid: tempProcess.pid,
+        });
+        tempProcess.kill('SIGKILL');
+        finalize('sigkill');
+      }, Math.max(0, GEMINI_KILL_GRACE_MS));
+    });
+  };
+
+  const appendTempStderrTail = (text: string) => {
+    tempStderrTail = `${tempStderrTail}${text}`;
+    if (tempStderrTail.length > stderrTailMaxChars) {
+      tempStderrTail = tempStderrTail.slice(-stderrTailMaxChars);
+    }
+  };
+
+  const clearTimers = () => {
+    if (noOutputTimeout) {
+      clearTimeout(noOutputTimeout);
+      noOutputTimeout = null;
+    }
+    if (overallTimeout) {
+      clearTimeout(overallTimeout);
+      overallTimeout = null;
+    }
+  };
+
+  const cleanup = async () => {
+    if (cleanedUp) {
+      return;
+    }
+    cleanedUp = true;
+    clearTimers();
+
+    try {
+      if (tempConnection && tempSessionId) {
+        await tempConnection.cancel({ sessionId: tempSessionId });
+      }
+    } catch (_) {
+    }
+
+    if (!tempProcess.killed && tempProcess.exitCode === null) {
+      await terminateProcessGracefully();
+    }
+
+    logInfo('Scheduler temp Gemini ACP process cleanup complete', {
+      scheduleId,
+      pid: tempProcess.pid,
+    });
+  };
+
+  tempProcess.stderr.on('data', (chunk: Buffer) => {
+    const rawText = chunk.toString();
+    appendTempStderrTail(rawText);
+    const text = rawText.trim();
+    if (text) {
+      console.error(`[gemini:scheduler:${scheduleId}] ${text}`);
+    }
+    tempCollector?.onActivity();
+  });
+
+  tempProcess.on('error', (error: Error) => {
+    logInfo('Scheduler temp Gemini ACP process error', {
+      scheduleId,
+      pid: tempProcess.pid,
+      error: error.message,
+    });
+  });
+
+  tempProcess.on('close', (code: number | null, signal: NodeJS.Signals | null) => {
+    logInfo('Scheduler temp Gemini ACP process exited', {
+      scheduleId,
+      pid: tempProcess.pid,
+      code,
+      signal,
+    });
+  });
+
+  try {
+    const input = Writable.toWeb(tempProcess.stdin) as unknown as WritableStream<Uint8Array>;
+    const output = Readable.toWeb(tempProcess.stdout) as unknown as ReadableStream<Uint8Array>;
+    const stream = acp.ndJsonStream(input, output);
+
+    const tempClient = {
+      async requestPermission(params: any) {
+        return buildPermissionResponse(params?.options, permissionStrategy);
+      },
+      async sessionUpdate(params: any) {
+        if (!tempCollector || params.sessionId !== tempSessionId) {
+          return;
+        }
+
+        tempCollector.onActivity();
+
+        if (params.update?.sessionUpdate === 'agent_message_chunk' && params.update?.content?.type === 'text') {
+          const chunkText = params.update.content.text;
+          tempCollector.append(chunkText);
+        }
+      },
+      async readTextFile(_params: any) {
+        return noOpAcpFileOperation(_params);
+      },
+      async writeTextFile(_params: any) {
+        return noOpAcpFileOperation(_params);
+      },
+    };
+
+    tempConnection = new acp.ClientSideConnection(() => tempClient, stream);
+
+    await tempConnection.initialize({
+      protocolVersion: acp.PROTOCOL_VERSION,
+      clientCapabilities: {},
+    });
+
+    const session = await tempConnection.newSession({
+      cwd,
+      mcpServers: [],
+    });
+    tempSessionId = session.sessionId;
+
+    return await new Promise<string>((resolve, reject) => {
+      let response = '';
+      let settled = false;
+      const startedAt = Date.now();
+      let chunkCount = 0;
+      let firstChunkAt: number | null = null;
+
+      const settle = async (handler: () => void) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        await cleanup();
+        handler();
+      };
+
+      const refreshNoOutputTimer = () => {
+        if (!noOutputTimeoutMs || noOutputTimeoutMs <= 0) {
+          return;
+        }
+        if (noOutputTimeout) {
+          clearTimeout(noOutputTimeout);
+        }
+        noOutputTimeout = setTimeout(async () => {
+          try {
+            if (tempConnection && tempSessionId) {
+              await tempConnection.cancel({ sessionId: tempSessionId });
+            }
+          } catch (_) {
+          }
+
+          await settle(() => reject(new Error(`Scheduler Gemini ACP produced no output for ${noOutputTimeoutMs}ms`)));
+        }, noOutputTimeoutMs);
+      };
+
+      overallTimeout = setTimeout(async () => {
+        try {
+          if (tempConnection && tempSessionId) {
+            await tempConnection.cancel({ sessionId: tempSessionId });
+          }
+        } catch (_) {
+        }
+
+        await settle(() => reject(new Error(`Scheduler Gemini ACP timed out after ${timeoutMs}ms`)));
+      }, timeoutMs);
+
+      tempCollector = {
+        onActivity: refreshNoOutputTimer,
+        append: (chunk: string) => {
+          refreshNoOutputTimer();
+          chunkCount += 1;
+          if (!firstChunkAt) {
+            firstChunkAt = Date.now();
+          }
+          if (ACP_DEBUG_STREAM) {
+            logInfo('Scheduler ACP chunk received', {
+              scheduleId,
+              chunkIndex: chunkCount,
+              chunkLength: chunk.length,
+              elapsedMs: Date.now() - startedAt,
+              bufferLengthBeforeAppend: response.length,
+            });
+          }
+          response += chunk;
+        },
+      };
+
+      refreshNoOutputTimer();
+
+      tempConnection.prompt({
+        sessionId: tempSessionId,
+        prompt: [{ type: 'text', text: promptForGemini }],
+      })
+        .then(async (result: any) => {
+          if (ACP_DEBUG_STREAM) {
+            logInfo('Scheduler ACP prompt stop reason', {
+              scheduleId,
+              stopReason: result?.stopReason || '(none)',
+              chunkCount,
+              firstChunkDelayMs: firstChunkAt ? firstChunkAt - startedAt : null,
+              elapsedMs: Date.now() - startedAt,
+              bufferedLength: response.length,
+            });
+          }
+          if (result?.stopReason === 'cancelled' && !response) {
+            await settle(() => reject(new Error('Scheduler Gemini ACP prompt was cancelled')));
+            return;
+          }
+
+          await settle(() => resolve(response || 'No response received.'));
+        })
+        .catch(async (error: any) => {
+          await settle(() => reject(new Error(error?.message || 'Scheduler Gemini ACP prompt failed')));
+        });
+    });
+  } catch (error: any) {
+    logInfo('Scheduler temporary Gemini ACP run failed', {
+      scheduleId,
+      error: getErrorMessage(error),
+      stderrTail: tempStderrTail || '(empty)',
+    });
+    throw error;
+  } finally {
+    await cleanup();
+  }
+}

package/agent-bridge.config.example.json

@@ -0,0 +1,19 @@
+{
+  "telegramToken": "your_telegram_bot_token_here",
+  "typingIntervalMs": 4000,
+  "geminiCommand": "gemini",
+  "geminiApprovalMode": "yolo",
+  "acpPermissionStrategy": "allow_once",
+  "geminiTimeoutMs": 900000,
+  "geminiNoOutputTimeoutMs": 60000,
+  "geminiKillGraceMs": 5000,
+  "acpStreamStdout": false,
+  "acpDebugStream": false,
+  "maxResponseLength": 4000,
+  "heartbeatIntervalMs": 60000,
+  "callbackHost": "localhost",
+  "callbackPort": 8788,
+  "callbackAuthToken": "",
+  "callbackMaxBodyBytes": 65536,
+  "schedulesFilePath": "~/.clawless/schedules.json"
+}