@cyanautomation/kaseki-agent 1.4.1

package/src/github-app-token.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+/**
+ * github-app-token.ts - Generate GitHub App installation access tokens
+ *
+ * Usage:
+ *   node dist/github-app-token.js <app-id> <private-key-file> <owner> <repo>
+ *
+ * Outputs JSON:
+ *   {
+ *     "token": "ghu_...",
+ *     "expires_at": "2026-04-26T...",
+ *     "error": "..." (if failed)
+ *   }
+ */
+
+import fs from 'fs';
+import crypto from 'crypto';
+import https from 'https';
+
+interface JWTHeader {
+  alg: string;
+  typ: string;
+}
+
+interface JWTPayload {
+  iss: string;
+  iat: number;
+  exp: number;
+}
+
+interface InstallationIdResponse {
+  id: number;
+  [key: string]: any;
+}
+
+interface AccessTokenResponse {
+  token: string;
+  expires_at: string;
+  [key: string]: any;
+}
+
+interface TokenResult {
+  token?: string;
+  expires_at?: string;
+  error?: string;
+}
+
+const APP_ID = process.argv[2];
+const PRIVATE_KEY_FILE = process.argv[3];
+const OWNER = process.argv[4];
+const REPO = process.argv[5];
+
+async function generateJWT(appId: string, privateKey: string): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  const iat = now - 60; // account for clock skew
+  const exp = now + 10 * 60; // 10 minutes
+
+  const header: JWTHeader = {
+    alg: 'RS256',
+    typ: 'JWT',
+  };
+
+  const payload: JWTPayload = {
+    iss: appId,
+    iat,
+    exp,
+  };
+
+  const headerBase64 = Buffer.from(JSON.stringify(header)).toString('base64url');
+  const payloadBase64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const message = `${headerBase64}.${payloadBase64}`;
+
+  // Sign with RSA-SHA256
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(message);
+  signer.end();
+
+  const signature = signer.sign(privateKey, 'base64url');
+  return `${message}.${signature}`;
+}
+
+async function getInstallationId(jwt: string, owner: string, repo: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path: `/repos/${owner}/${repo}/installation`,
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${jwt}`,
+        'Accept': 'application/vnd.github.machine-man-preview+json',
+        'User-Agent': 'Kaseki-Agent',
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(
+            new Error(
+              `Failed to get installation ID: ${res.statusCode} ${data}`
+            )
+          );
+        } else {
+          try {
+            const json: InstallationIdResponse = JSON.parse(data);
+            resolve(json.id);
+          } catch (e) {
+            reject(
+              new Error(
+                `Failed to parse installation response: ${
+                  e instanceof Error ? e.message : String(e)
+                }`
+              )
+            );
+          }
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function getAccessToken(
+  jwt: string,
+  installationId: number
+): Promise<AccessTokenResponse> {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path: `/app/installations/${installationId}/access_tokens`,
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${jwt}`,
+        'Accept': 'application/vnd.github.machine-man-preview+json',
+        'User-Agent': 'Kaseki-Agent',
+        'Content-Length': '0',
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        if (res.statusCode !== 201) {
+          reject(
+            new Error(`Failed to get access token: ${res.statusCode} ${data}`)
+          );
+        } else {
+          try {
+            const json: AccessTokenResponse = JSON.parse(data);
+            resolve({
+              token: json.token,
+              expires_at: json.expires_at,
+            });
+          } catch (e) {
+            reject(
+              new Error(
+                `Failed to parse token response: ${
+                  e instanceof Error ? e.message : String(e)
+                }`
+              )
+            );
+          }
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function main(): Promise<void> {
+  if (!APP_ID || !PRIVATE_KEY_FILE || !OWNER || !REPO) {
+    console.error(
+      'Usage: node github-app-token.js <app-id> <private-key-file> <owner> <repo>'
+    );
+    process.exit(1);
+  }
+
+  try {
+    // Read private key
+    const privateKey = fs.readFileSync(PRIVATE_KEY_FILE, 'utf8');
+
+    // Generate JWT
+    const jwt = await generateJWT(APP_ID, privateKey);
+
+    // Get installation ID
+    const installationId = await getInstallationId(jwt, OWNER, REPO);
+
+    // Get access token
+    const tokenData = await getAccessToken(jwt, installationId);
+
+    // Output result as JSON
+    console.log(JSON.stringify(tokenData));
+  } catch (error) {
+    // Output error as JSON
+    const result: TokenResult = {
+      error: error instanceof Error ? error.message : String(error),
+    };
+    console.log(JSON.stringify(result));
+    process.exit(1);
+  }
+}
+
+main();

package/src/idempotency-store.test.ts

@@ -0,0 +1,117 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { IdempotencyStore } from './idempotency-store';
+import { RunResponse } from './kaseki-api-types';
+
+describe('IdempotencyStore persistence', () => {
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kaseki-idempotency-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('restores exact fulfilled response payload across restart', () => {
+    const key = 'a-key';
+    const fingerprint = 'fp-1';
+    const response: RunResponse = {
+      id: 'kaseki-42',
+      status: 'queued',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      requestId: '11111111-1111-4111-8111-111111111111',
+      correlationId: '22222222-2222-4222-8222-222222222222',
+      error: 'transient warning',
+    };
+
+    const store1 = new IdempotencyStore(resultsDir, 24);
+    expect(store1.claimOrGet(key, fingerprint)).toEqual({ kind: 'claimed' });
+    store1.storeResponse(key, response, fingerprint);
+    expect(store1.claimOrGet(key, fingerprint)).toEqual({ kind: 'fulfilled', response });
+    store1.shutdown();
+
+    const store2 = new IdempotencyStore(resultsDir, 24);
+    expect(store2.claimOrGet(key, fingerprint)).toEqual({ kind: 'fulfilled', response });
+    store2.shutdown();
+  });
+
+  test('supports older log lines without responsePayload fields', () => {
+    const persistencePath = path.join(resultsDir, '.kaseki-api-idempotency.jsonl');
+    const legacyLine = {
+      idempotencyKey: 'legacy-key',
+      requestFingerprint: 'legacy-fp',
+      state: 'fulfilled',
+      jobId: 'kaseki-legacy',
+      requestTime: '2026-01-02T00:00:00.000Z',
+      requestId: '33333333-3333-4333-8333-333333333333',
+      correlationId: '44444444-4444-4444-8444-444444444444',
+      expiresAt: Date.now() + 24 * 3600 * 1000,
+    };
+
+    fs.writeFileSync(persistencePath, `${JSON.stringify(legacyLine)}\n`, 'utf-8');
+
+    const store = new IdempotencyStore(resultsDir, 24);
+    expect(store.claimOrGet('legacy-key', 'legacy-fp')).toEqual({
+      kind: 'fulfilled',
+      response: {
+        id: 'kaseki-legacy',
+        status: 'queued',
+        createdAt: '2026-01-02T00:00:00.000Z',
+        requestId: '33333333-3333-4333-8333-333333333333',
+        correlationId: '44444444-4444-4444-8444-444444444444',
+      },
+    });
+    store.shutdown();
+  });
+
+  test('only one parallel claimer gets claimed for the same key', async () => {
+    const workerPath = path.join(resultsDir, 'claim-worker.ts');
+    fs.writeFileSync(
+      workerPath,
+      `
+      import { IdempotencyStore } from '${path.resolve('src/idempotency-store.ts').replace(/\\/g, '\\\\')}';
+      const [resultsDir, key, fingerprint] = process.argv.slice(2);
+      const store = new IdempotencyStore(resultsDir, 24);
+      const result = store.claimOrGet(key, fingerprint);
+      store.shutdown();
+      process.stdout.write(JSON.stringify(result));
+    `,
+      'utf-8'
+    );
+
+    const claimFromProcess = (): Promise<{ kind: string }> =>
+      new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, ['--import', 'tsx', workerPath, resultsDir, 'concurrent-key', 'same-fp']);
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout.on('data', (chunk) => {
+          stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+          stderr += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+          if (code !== 0) {
+            reject(new Error(`worker exited with code ${code}: ${stderr}`));
+            return;
+          }
+          const lines = stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith('{') && line.endsWith('}'));
+          resolve(JSON.parse(lines[lines.length - 1]) as { kind: string });
+        });
+      });
+
+    const [result1, result2] = await Promise.all([claimFromProcess(), claimFromProcess()]);
+    const kinds = [result1.kind, result2.kind].sort();
+
+    expect(kinds).toEqual(['claimed', 'pending']);
+  }, 15000);
+});

package/src/idempotency-store.ts

@@ -0,0 +1,385 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { RunResponse } from './kaseki-api-types';
+import { createEventLogger, EventLogger } from './logger';
+
+/**
+ * Idempotency cache entry.
+ */
+interface IdempotencyCacheEntry {
+  idempotencyKey: string;
+  requestFingerprint: string;
+  state: 'pending' | 'fulfilled';
+  jobId: string;
+  requestTime: string; // ISO 8601
+  responsePayload: RunResponse;
+  expiresAt: number; // Unix timestamp
+}
+
+interface PersistedIdempotencyEntry {
+  idempotencyKey: string;
+  requestFingerprint?: string;
+  state?: 'pending' | 'fulfilled';
+  jobId?: string;
+  requestTime?: string;
+  responsePayload?: RunResponse;
+  requestId?: string;
+  correlationId?: string;
+  expiresAt: number;
+}
+
+export type ClaimResult =
+  | { kind: 'claimed' }
+  | { kind: 'pending' }
+  | { kind: 'fulfilled'; response: RunResponse };
+
+/**
+ * Idempotency store manages request deduplication with persistent storage.
+ * Ensures safe retries: same idempotency key always returns the same job ID.
+ */
+export class IdempotencyStore {
+  private cache = new Map<string, IdempotencyCacheEntry>();
+  private persistencePath: string;
+  private lockPath: string;
+  private logger: EventLogger;
+  private ttlHours: number;
+  private cleanupInterval: NodeJS.Timeout | null = null;
+  private lastReadPosition = 0;
+  private readRemainder = '';
+
+  constructor(resultsDir: string, ttlHours: number = 24) {
+    this.persistencePath = path.join(resultsDir, '.kaseki-api-idempotency.jsonl');
+    this.lockPath = path.join(resultsDir, '.kaseki-api-idempotency.lock');
+    this.logger = createEventLogger('idempotency-store');
+    this.ttlHours = ttlHours;
+    this.loadFromDisk();
+    this.startCleanup();
+  }
+
+  /**
+   * Check if idempotency key has been seen before and return cached response.
+   */
+  claimOrGet(idempotencyKey: string, requestFingerprint: string): ClaimResult {
+    return this.withLock(() => {
+      this.loadFromDisk();
+      const entry = this.cache.get(idempotencyKey);
+      if (!entry || Date.now() > entry.expiresAt) {
+        const pendingEntry: IdempotencyCacheEntry = {
+          idempotencyKey,
+          requestFingerprint,
+          state: 'pending',
+          jobId: '',
+          requestTime: new Date().toISOString(),
+          responsePayload: {
+            id: '',
+            status: 'queued',
+            createdAt: new Date().toISOString(),
+          },
+          expiresAt: Date.now() + this.ttlHours * 3600 * 1000,
+        };
+
+        this.cache.set(idempotencyKey, pendingEntry);
+        this.persistToDisk(pendingEntry);
+        return { kind: 'claimed' };
+      }
+
+      if (entry.requestFingerprint !== requestFingerprint) {
+        throw new Error('Idempotency key has already been used with a different request payload');
+      }
+
+      if (entry.state === 'pending') {
+        return { kind: 'pending' };
+      }
+
+      this.logger.event('idempotency_cache_hit', {
+        idempotencyKey,
+        jobId: entry.jobId,
+        ageSeconds: Math.round((Date.now() - new Date(entry.requestTime).getTime()) / 1000),
+      });
+
+      return { kind: 'fulfilled', response: entry.responsePayload };
+    });
+  }
+
+  /**
+   * Store a new idempotency entry.
+   */
+  storeResponse(idempotencyKey: string, response: RunResponse, requestFingerprint: string): void {
+    this.withLock(() => {
+      this.loadFromDisk();
+      const existing = this.cache.get(idempotencyKey);
+      const entry: IdempotencyCacheEntry = existing
+        ? {
+          ...existing,
+          requestFingerprint,
+          state: 'fulfilled',
+          jobId: response.id,
+          responsePayload: response,
+        }
+        : {
+          idempotencyKey,
+          requestFingerprint,
+          state: 'fulfilled',
+          jobId: response.id,
+          requestTime: new Date().toISOString(),
+          responsePayload: response,
+          expiresAt: Date.now() + this.ttlHours * 3600 * 1000,
+        };
+
+      this.cache.set(idempotencyKey, entry);
+      this.persistToDisk(entry);
+
+      this.logger.event('idempotency_cache_store', {
+        idempotencyKey,
+        jobId: response.id,
+        ttlHours: this.ttlHours,
+      });
+    });
+  }
+
+  private withLock<T>(fn: () => T): T {
+    this.acquireLock();
+    try {
+      return fn();
+    } finally {
+      this.releaseLock();
+    }
+  }
+
+  private acquireLock(): void {
+    const maxRetries = 600; // 3 seconds total (600 * 5ms)
+    const staleThresholdMs = 30000; // 30 seconds
+    let retries = 0;
+
+    while (retries < maxRetries) {
+      try {
+        fs.mkdirSync(this.lockPath);
+        return;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+          throw error;
+        }
+        try {
+          const stats = fs.statSync(this.lockPath);
+          if (Date.now() - stats.mtimeMs > staleThresholdMs) {
+            fs.rmdirSync(this.lockPath);
+            continue;
+          }
+        } catch {
+          // If stale-lock check/removal fails, proceed to retry sleep.
+        }
+
+        this.sleepSync(5);
+        retries++;
+      }
+    }
+
+    throw new Error('Failed to acquire lock after maximum retries');
+  }
+
+  private releaseLock(): void {
+    try {
+      fs.rmdirSync(this.lockPath);
+    } catch {
+      // Ignore lock release failures.
+    }
+  }
+
+  private sleepSync(ms: number): void {
+    const start = Date.now();
+    while (Date.now() - start < ms) {
+      // Busy wait
+    }
+  }
+
+  /**
+   * Persist a single entry to disk (append-only log).
+   */
+  private persistToDisk(entry: IdempotencyCacheEntry): void {
+    try {
+      const line = JSON.stringify({
+        idempotencyKey: entry.idempotencyKey,
+        requestFingerprint: entry.requestFingerprint,
+        state: entry.state,
+        jobId: entry.jobId,
+        requestTime: entry.requestTime,
+        responsePayload: entry.responsePayload,
+        expiresAt: entry.expiresAt,
+      });
+
+      fs.appendFileSync(this.persistencePath, `${line}\n`, 'utf-8');
+    } catch (error) {
+      this.logger.error('Failed to persist idempotency entry', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Load idempotency entries from disk.
+   */
+  private loadFromDisk(): void {
+    try {
+      if (!fs.existsSync(this.persistencePath)) {
+        return;
+      }
+
+      const stats = fs.statSync(this.persistencePath);
+      if (stats.size < this.lastReadPosition) {
+        this.lastReadPosition = 0;
+        this.readRemainder = '';
+        this.cache.clear();
+      }
+
+      if (stats.size === this.lastReadPosition) {
+        return;
+      }
+
+      const fileDescriptor = fs.openSync(this.persistencePath, 'r');
+      let lines: string[] = [];
+      try {
+        const bytesToRead = stats.size - this.lastReadPosition;
+        const buffer = Buffer.alloc(bytesToRead);
+        fs.readSync(fileDescriptor, buffer, 0, bytesToRead, this.lastReadPosition);
+        this.lastReadPosition = stats.size;
+
+        const content = this.readRemainder + buffer.toString('utf-8');
+        lines = content.split('\n');
+        this.readRemainder = lines.pop() ?? '';
+      } finally {
+        fs.closeSync(fileDescriptor);
+      }
+
+      for (const line of lines) {
+        if (!line.trim()) {
+          continue;
+        }
+        try {
+          const entry = JSON.parse(line) as PersistedIdempotencyEntry;
+
+          // Skip expired entries
+          if (Date.now() > entry.expiresAt) {
+            continue;
+          }
+
+          const requestTime = entry.requestTime || '1970-01-01T00:00:00.000Z';
+          const jobId = entry.jobId || entry.responsePayload?.id || '';
+          const restoredResponse: RunResponse = entry.responsePayload || {
+            id: jobId,
+            status: 'queued',
+            createdAt: requestTime,
+            requestId: entry.requestId,
+            correlationId: entry.correlationId,
+          };
+
+          // Store in cache
+          this.cache.set(entry.idempotencyKey, {
+            idempotencyKey: entry.idempotencyKey,
+            requestFingerprint: entry.requestFingerprint || '',
+            state: entry.state || 'fulfilled',
+            jobId,
+            requestTime,
+            responsePayload: restoredResponse,
+            expiresAt: entry.expiresAt,
+          });
+        } catch {
+          // Skip invalid JSON lines
+        }
+      }
+
+      this.logger.event('idempotency_loaded', {
+        entriesLoaded: this.cache.size,
+      });
+    } catch (error) {
+      this.logger.error('Failed to load idempotency store from disk', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Start periodic cleanup of expired entries.
+   */
+  private startCleanup(): void {
+    if (this.cleanupInterval) {
+      return;
+    }
+
+    // Run cleanup every hour (but allow process to exit even if interval is pending)
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, 3600000);
+    this.cleanupInterval.unref();
+  }
+
+  /**
+   * Clean up expired entries and rewrite the log file.
+   */
+  private cleanup(): void {
+    try {
+      const now = Date.now();
+      let removedCount = 0;
+
+      // Remove expired entries from cache
+      for (const [key, entry] of this.cache.entries()) {
+        if (now > entry.expiresAt) {
+          this.cache.delete(key);
+          removedCount++;
+        }
+      }
+
+      // Rewrite persistence file with only valid entries
+      if (removedCount > 0) {
+        const validEntries: string[] = [];
+        for (const entry of this.cache.values()) {
+          validEntries.push(
+            JSON.stringify({
+              idempotencyKey: entry.idempotencyKey,
+              requestFingerprint: entry.requestFingerprint,
+              state: entry.state,
+              jobId: entry.jobId,
+              requestTime: entry.requestTime,
+              responsePayload: entry.responsePayload,
+              expiresAt: entry.expiresAt,
+            })
+          );
+        }
+
+        fs.writeFileSync(this.persistencePath, validEntries.join('\n') + (validEntries.length > 0 ? '\n' : ''), 'utf-8');
+
+        this.logger.event('idempotency_cleanup', {
+          removedEntries: removedCount,
+          remainingEntries: this.cache.size,
+        });
+      }
+    } catch (error) {
+      this.logger.error('Idempotency cleanup failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Get current cache size.
+   */
+  getSize(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Gracefully shutdown the store.
+   */
+  shutdown(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+
+    // Run final cleanup
+    this.cleanup();
+
+    this.logger.event('idempotency_store_shutdown', {
+      entriesRemaining: this.cache.size,
+    });
+  }
+}