@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/protocols/a2a/jsonrpc-v1.js

@@ -0,0 +1,145 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { TaskStatus } from './index.js';
+const identifier = z.string().min(1).max(128).regex(/^[A-Za-z0-9_.:-]+$/);
+const requestSchema = z.object({ jsonrpc: z.literal('2.0'), id: z.union([z.string().max(128), z.number().finite(), z.null()]), method: z.string().max(64), params: z.record(z.string(), z.unknown()).default({}) }).strict();
+const messageSchema = z.object({ messageId: identifier, contextId: identifier.optional(), role: z.enum(['ROLE_USER', 'user']).optional(),
+    parts: z.array(z.object({ text: z.string(), type: z.literal('text').optional(), kind: z.literal('text').optional() }).strict()).min(1).max(64) }).strict();
+const MAX_TEXT = 64 * 1024;
+const timestamp = () => new Date().toISOString();
+function truncateUtf8(text, limit) {
+    const buffer = Buffer.from(text);
+    let end = Math.min(buffer.length, limit);
+    while (end > 0 && end < buffer.length && (buffer[end] & 0xc0) === 0x80)
+        end--;
+    return buffer.subarray(0, end).toString('utf8');
+}
+export const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+/** Bounded text-only A2A 1.0 JSON-RPC subset; no automatic retries, streaming or pretend cancellation. */
+export class A2AJsonRpcAdapter {
+    executor;
+    timeoutMs;
+    peerCount;
+    tasks = new Map();
+    messages = new Map();
+    contexts = new Map();
+    constructor(executor, timeoutMs = 120000, peerCount = 1) {
+        this.executor = executor;
+        this.timeoutMs = timeoutMs;
+        this.peerCount = peerCount;
+    }
+    async handle(peer, input, version) {
+        const parsed = requestSchema.safeParse(input);
+        if (!parsed.success)
+            return rpcError(null, -32600, 'Invalid JSON-RPC request');
+        const { id, method, params } = parsed.data;
+        if (version && !['1.0', '1.0.0'].includes(version))
+            return rpcError(id, -32602, 'Only A2A 1.0 is supported');
+        this.prune();
+        if (method === 'GetTask' || method === 'tasks/get') {
+            const key = typeof params.id === 'string' ? params.id : typeof params.name === 'string' ? params.name.replace(/^tasks\//, '') : '';
+            const stored = this.tasks.get(key);
+            return stored?.peer === peer ? { jsonrpc: '2.0', id, result: structuredClone(stored.task) } : rpcError(id, -32001, 'Task not found');
+        }
+        if (method === 'CancelTask' || method === 'tasks/cancel')
+            return rpcError(id, -32004, 'Cancellation is not supported; no cancellation was performed');
+        if (!['SendMessage', 'message/send'].includes(method))
+            return rpcError(id, -32601, 'Method not supported (including streaming)');
+        const message = messageSchema.safeParse(params.message);
+        if (!message.success)
+            return rpcError(id, -32602, 'A text message with messageId is required');
+        const text = message.data.parts.map(p => p.text).join('\n').trim();
+        if (!text || Buffer.byteLength(text) > MAX_TEXT)
+            return rpcError(id, -32602, 'Message must contain 1–65536 UTF-8 bytes');
+        if (params.contextId !== undefined && !identifier.safeParse(params.contextId).success)
+            return rpcError(id, -32602, 'Invalid contextId');
+        if (params.configuration !== undefined && (!params.configuration || typeof params.configuration !== 'object' || params.configuration.blocking !== true))
+            return rpcError(id, -32602, 'Only blocking SendMessage is supported');
+        const contextId = message.data.contextId ?? (typeof params.contextId === 'string' && identifier.safeParse(params.contextId).success ? params.contextId : randomUUID());
+        const fingerprint = createHash('sha256').update(JSON.stringify([message.data.contextId ?? params.contextId ?? null, text])).digest('hex');
+        const messageKey = `${peer}:${message.data.messageId}`;
+        const previousId = this.messages.get(messageKey);
+        const previous = previousId ? this.tasks.get(previousId) : undefined;
+        if (previous) {
+            if (previous.fingerprint !== fingerprint)
+                return rpcError(id, -32602, 'messageId already used with different content');
+            return { jsonrpc: '2.0', id, result: { task: await (previous.promise ?? Promise.resolve(structuredClone(previous.task))) } };
+        }
+        const contextKey = `${peer}:${contextId}`;
+        const context = this.contexts.get(contextKey) ?? { messages: [], turns: 0, busy: false, at: Date.now() };
+        if (context.messages.reduce((bytes, msg) => bytes + Buffer.byteLength(JSON.stringify(msg)), Buffer.byteLength(text)) > MAX_TEXT)
+            return rpcError(id, -32602, 'Context text limit reached');
+        if (context.busy)
+            return rpcError(id, -32005, 'Context is busy; no second task was started');
+        if (context.turns >= 5)
+            return rpcError(id, -32005, 'Context turn limit reached');
+        const shares = Math.max(1, Math.min(32, Math.floor(this.peerCount)));
+        const peerTasks = [...this.tasks.values()].filter(value => value.peer === peer).length;
+        const peerContexts = [...this.contexts.keys()].filter(key => key.startsWith(`${peer}:`)).length;
+        if (peerTasks >= Math.floor(256 / shares) || (!this.contexts.has(contextKey) && peerContexts >= Math.floor(128 / shares)))
+            return rpcError(id, -32005, 'Peer task capacity reached');
+        if (this.tasks.size >= 256 || (!this.contexts.has(contextKey) && this.contexts.size >= 128))
+            return rpcError(id, -32005, 'Task capacity reached');
+        const task = { id: randomUUID(), contextId, status: { state: 'TASK_STATE_WORKING', timestamp: timestamp() }, artifacts: [] };
+        const stored = { peer, contextId, fingerprint, task, at: Date.now() };
+        this.tasks.set(task.id, stored);
+        this.messages.set(messageKey, task.id);
+        if (text.startsWith('/')) {
+            task.status = { state: 'TASK_STATE_REJECTED', timestamp: timestamp(), message: { role: 'ROLE_AGENT', parts: [{ text: 'Slash commands are not allowed over A2A' }] } };
+            return { jsonrpc: '2.0', id, result: { task: structuredClone(task) } };
+        }
+        context.busy = true;
+        context.turns++;
+        context.at = Date.now();
+        this.contexts.set(contextKey, context);
+        const inputTask = { id: task.id, sessionId: `a2a:${peer}:${contextId}`, metadata: { peerId: peer },
+            messages: [...structuredClone(context.messages), { role: 'user', parts: [{ type: 'text', text }] }], artifacts: [], history: [], status: { status: TaskStatus.WORKING, timestamp: Date.now() } };
+        const controller = new AbortController();
+        let timer;
+        stored.running = true;
+        const execution = Promise.resolve().then(() => this.executor(inputTask, controller.signal)).finally(() => { context.busy = false; stored.running = false; });
+        stored.promise = (async () => {
+            try {
+                const completed = await Promise.race([execution, new Promise((_, reject) => {
+                        timer = setTimeout(() => { controller.abort(); reject(new Error('TIMEOUT')); }, this.timeoutMs);
+                        timer.unref?.();
+                    })]);
+                const failed = completed.status.status !== TaskStatus.COMPLETED;
+                const output = completed.messages.filter(m => m.role === 'agent').at(-1)?.parts.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
+                task.status = { state: failed ? 'TASK_STATE_FAILED' : 'TASK_STATE_COMPLETED', timestamp: timestamp() };
+                if (!failed) {
+                    const returnedText = Buffer.byteLength(output) > MAX_TEXT ? truncateUtf8(output, MAX_TEXT - 32) + '\n[Output truncated]' : output;
+                    task.artifacts = [{ artifactId: randomUUID(), parts: [{ text: returnedText }] }];
+                    context.messages = [...structuredClone(completed.messages).slice(0, -1), { role: 'agent', parts: [{ type: 'text', text: returnedText }] }].slice(-10);
+                    while (context.messages.length > 1 && Buffer.byteLength(JSON.stringify(context.messages)) > MAX_TEXT)
+                        context.messages.shift();
+                }
+                else
+                    task.status.message = { role: 'ROLE_AGENT', parts: [{ text: 'Executor failed; inspect local diagnostics' }] };
+            }
+            catch {
+                task.status = { state: 'TASK_STATE_FAILED', timestamp: timestamp(), message: { role: 'ROLE_AGENT', parts: [{ text: 'Execution failed or timed out; no automatic retry' }] } };
+            }
+            finally {
+                clearTimeout(timer);
+                stored.promise = undefined;
+                stored.at = Date.now();
+            }
+            return structuredClone(task);
+        })();
+        return { jsonrpc: '2.0', id, result: { task: await stored.promise } };
+    }
+    prune() {
+        const cutoff = Date.now() - 30 * 60 * 1000;
+        for (const [id, value] of this.tasks)
+            if (!value.running && !value.promise && value.at < cutoff)
+                this.tasks.delete(id);
+        for (const [id, taskId] of this.messages)
+            if (!this.tasks.has(taskId))
+                this.messages.delete(id);
+        for (const [id, context] of this.contexts)
+            if (!context.busy && context.at < cutoff)
+                this.contexts.delete(id);
+    }
+}
+//# sourceMappingURL=jsonrpc-v1.js.map

package/dist/protocols/a2a/peer-config.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+declare const schema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    inboundTokenEnv: z.ZodOptional<z.ZodString>;
+    outboundTokenEnv: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url?: string | undefined;
+    inboundTokenEnv?: string | undefined;
+    outboundTokenEnv?: string | undefined;
+}, {
+    url?: string | undefined;
+    inboundTokenEnv?: string | undefined;
+    outboundTokenEnv?: string | undefined;
+}>>;
+export type A2APeers = z.infer<typeof schema>;
+export declare function readA2APeers(raw?: string | undefined): A2APeers;
+export declare function validateA2AUrl(raw: string): URL;
+export declare function a2aToken(reference?: string): string | undefined;
+export declare function authenticateA2APeer(peers: A2APeers, authorization?: string): string | undefined;
+export {};

package/dist/protocols/a2a/peer-config.js

@@ -0,0 +1,55 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+const envRef = z.string().regex(/^[A-Z][A-Z0-9_]{0,95}$/);
+const schema = z.record(z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/), z.object({
+    url: z.string().optional(), inboundTokenEnv: envRef.optional(), outboundTokenEnv: envRef.optional(),
+}).strict());
+export function readA2APeers(raw = process.env.CODEBUDDY_A2A_PEERS) {
+    if (!raw)
+        return {};
+    try {
+        if (raw.length > 16384)
+            throw new Error();
+        const result = schema.parse(JSON.parse(raw));
+        if (Object.keys(result).length > 32)
+            throw new Error();
+        for (const peer of Object.values(result))
+            if (peer.url)
+                validateA2AUrl(peer.url);
+        return result;
+    }
+    catch {
+        throw new Error('Invalid CODEBUDDY_A2A_PEERS configuration (URLs and environment references only)');
+    }
+}
+export function validateA2AUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('Invalid configured A2A URL');
+    }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash
+        || (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+        throw new Error('A2A requires HTTPS or loopback HTTP, without URL credentials/query/fragment');
+    }
+    return url;
+}
+export function a2aToken(reference) {
+    const value = reference ? process.env[reference] : undefined;
+    return value && value.length >= 16 && value.length <= 16384 && !/[\r\n]/.test(value) ? value : undefined;
+}
+export function authenticateA2APeer(peers, authorization) {
+    if (!authorization?.startsWith('Bearer ') || authorization.length > 16400)
+        return undefined;
+    const hash = (value) => createHash('sha256').update(value).digest();
+    const presented = hash(authorization.slice(7));
+    const matches = Object.entries(peers).filter(([, config]) => {
+        const token = a2aToken(config.inboundTokenEnv);
+        return token && timingSafeEqual(hash(token), presented);
+    });
+    // Duplicate credentials are ambiguous identities; fail closed.
+    return matches.length === 1 ? matches[0]?.[0] : undefined;
+}
+//# sourceMappingURL=peer-config.js.map

package/dist/providers/codex-oauth.js

@@ -56,12 +56,21 @@ const TOKEN_REFRESH_AGE_MS = 60 * 60 * 1000; // 1 hour
  * the same rotating refresh token more than once. */
 let refreshAuthInFlight = null;
 const AUTH_FILE_PATH = path.join(os.homedir(), '.codebuddy', 'codex-auth.json');
+const CODEX_CLI_AUTH_PATH = path.join(os.homedir(), '.codex', 'auth.json');
 // ─────────────────────────────────────────────────────────────────────
 // Storage
 // ─────────────────────────────────────────────────────────────────────
 function loadAuthFile() {
     try {
-        return readJsonAtomicSync(AUTH_FILE_PATH, null);
+        const primary = readJsonAtomicSync(AUTH_FILE_PATH, null);
+        if (primary?.tokens?.access_token)
+            return primary;
+        if (fs.existsSync(CODEX_CLI_AUTH_PATH)) {
+            const fallback = readJsonAtomicSync(CODEX_CLI_AUTH_PATH, null);
+            if (fallback?.tokens?.access_token)
+                return fallback;
+        }
+        return primary;
     }
     catch (err) {
         logger.error('Error reading codex-auth.json', err instanceof Error ? err : { error: String(err) });
@@ -72,8 +81,10 @@ function saveAuthFile(auth) {
     try {
         writeJsonAtomicSync(AUTH_FILE_PATH, auth, { mode: 0o600 });
     }
-    catch (err) {
-        logger.error('Error writing codex-auth.json', err instanceof Error ? err : { error: String(err) });
+    catch {
+        // A successful exchange is not a successful login until tokens survive
+        // a restart. Never return freshly rotated tokens as if they were saved.
+        throw new Error('Could not save ChatGPT credentials. Check file permissions and available disk space, then run `buddy login` again.');
     }
 }
 /** Remove cached tokens. `/logout chatgpt` calls this. */
@@ -92,9 +103,13 @@ export function clearCodexCredentials() {
 export function hasCodexCredentials() {
     try {
         const parsed = readJsonAtomicSync(AUTH_FILE_PATH, null);
-        if (!parsed)
-            return false;
-        return Boolean(parsed.tokens?.access_token);
+        if (parsed?.tokens?.access_token)
+            return true;
+        if (fs.existsSync(CODEX_CLI_AUTH_PATH)) {
+            const fallback = readJsonAtomicSync(CODEX_CLI_AUTH_PATH, null);
+            return Boolean(fallback?.tokens?.access_token);
+        }
+        return false;
     }
     catch {
         return false;
@@ -343,7 +358,9 @@ export function loginInteractive(openUrl) {
         let serverInstance = null;
         let timeoutHandle = null;
         let actualPort = CALLBACK_PORT;
+        let finished = false;
         const cleanup = () => {
+            finished = true;
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
             if (serverInstance) {
@@ -392,6 +409,13 @@ export function loginInteractive(openUrl) {
                 }
                 const redirectUri = `http://localhost:${actualPort}/auth/callback`;
                 const tokens = await exchangeCodeForTokens(code, pkce.code_verifier, redirectUri);
+                if (finished) {
+                    // Cancellation/timeout may happen while the issuer is responding.
+                    // A late response must not replace credentials after the UI has ended.
+                    res.writeHead(410, { 'Content-Type': 'text/plain' });
+                    res.end('Login is no longer active. Run buddy login again.');
+                    return;
+                }
                 const authFile = {
                     tokens,
                     last_refresh: new Date().toISOString(),

package/dist/providers/model-provider-compat.js

@@ -1,3 +1,4 @@
+import { isChatGptSubscriptionModel } from './chatgpt-models.js';
 /**
  * Model ↔ provider compatibility for the CLI model resolver (`loadModel`).
  *
@@ -35,7 +36,7 @@ export function isModelCompatibleWithProvider(model, provider) {
     if (provider === 'grok')
         return looksGrok;
     if (provider === 'chatgpt')
-        return /^(gpt-|o[1-9]|codex)/i.test(model) && !looksGrok;
+        return isChatGptSubscriptionModel(model) && !looksGrok;
     if (LOCAL_RUNTIME_PROVIDERS.has(provider))
         return !looksLikeCloudModel(model);
     if (FIRST_PARTY_PROVIDERS.has(provider)) {

package/dist/sandbox/os-sandbox.d.ts

@@ -240,4 +240,4 @@ export declare function createSandboxConfigForMode(mode: SandboxMode, cwd?: stri
 export declare function createSandboxForMode(mode: SandboxMode, cwd?: string, extraReadOnly?: string[], extraReadWrite?: string[]): Promise<OSSandbox>;
 export declare function getOSSandbox(config?: Partial<OSSandboxConfig>): OSSandbox;
 export declare function resetOSSandbox(): void;
-export { OSSandboxConfig as OSConfig };
+export type { OSSandboxConfig as OSConfig };

package/dist/scheduler/cron-scheduler.d.ts

@@ -11,6 +11,7 @@
 import { EventEmitter } from 'events';
 import type { CronPreCheck } from './pre-check-runner.js';
 import type { CronWatchdog } from './watchdog-handlers.js';
+import { type ContinuityFlag } from './job-notepad.js';
 export type ScheduleType = 'at' | 'every' | 'cron';
 export type JobStatus = 'active' | 'paused' | 'completed' | 'error';
 export interface CronJob {
@@ -78,9 +79,17 @@ export interface CronJob {
     /**
      * Optional non-LLM pre-check. When present, it is evaluated before the task;
      * if it decides nothing changed, the expensive task is skipped with evidence.
-     * `lastFingerprint` is updated and persisted across runs by the bridge.
+     * `lastFingerprint` is updated and persisted across runs by the bridge,
+     * but only after a successful evaluation (skip or completed task) — a failed
+     * run must not consume the fingerprint, so an unchanged source can retry.
      */
     preCheck?: CronPreCheck;
+    /**
+     * Opt-in per-job bounded continuity (scratchpad + last successful output).
+     * Off by default: agent prompts stay byte-identical. Notes passed at
+     * create/update are stored in the isolated notepad file, not in jobs.json.
+     */
+    continuity?: ContinuityFlag;
     /** Delivery options */
     delivery?: {
         /** Delivery mode: 'channel' (default), 'webhook', or 'none' (silent, no notification) */
@@ -175,7 +184,10 @@ export declare class CronScheduler extends EventEmitter {
     private tickInFlight;
     private running;
     private taskExecutor?;
+    private notepad;
     constructor(config?: Partial<CronSchedulerConfig>);
+    /** Directory of isolated per-job notepad files (`<cron-root>/notepads`). */
+    get notepadDir(): string;
     /**
      * Set the task executor (for CronAgentBridge integration)
      */
@@ -205,11 +217,12 @@ export declare class CronScheduler extends EventEmitter {
         sessionTarget?: CronJob['sessionTarget'];
         preCheck?: CronJob['preCheck'];
         then?: string;
+        continuity?: CronJob['continuity'];
     }): Promise<CronJob>;
     /**
      * Update a job
      */
-    updateJob(jobId: string, updates: Partial<Pick<CronJob, 'name' | 'description' | 'type' | 'schedule' | 'task' | 'delivery' | 'maxRuns' | 'enabled' | 'preCheck' | 'then'>>): Promise<CronJob | null>;
+    updateJob(jobId: string, updates: Partial<Pick<CronJob, 'name' | 'description' | 'type' | 'schedule' | 'task' | 'delivery' | 'maxRuns' | 'enabled' | 'preCheck' | 'then' | 'continuity'>>): Promise<CronJob | null>;
     /**
      * Remove a job
      */

package/dist/scheduler/cron-scheduler.js

@@ -17,6 +17,7 @@ import { logger } from '../utils/logger.js';
 import { canonicalizeTimeZone } from '../life-rhythm/day-context.js';
 import { findNextZonedMinute } from '../life-rhythm/zoned-minute.js';
 import { readJsonAtomic, readTextAtomic, writeFileAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
+import { JobNotepadStore, isContinuityEnabled, persistableContinuity, validateContinuity, } from './job-notepad.js';
 /** Exponential backoff delays in ms: 30s, 1m, 5m, 15m, 60m */
 const BACKOFF_DELAYS_MS = [30_000, 60_000, 300_000, 900_000, 3_600_000];
 /** Maximum chain depth to guard against cyclic `then` references (A→B→A). */
@@ -194,9 +195,15 @@ export class CronScheduler extends EventEmitter {
     tickInFlight = false;
     running = false;
     taskExecutor;
+    notepad;
     constructor(config = {}) {
         super();
         this.config = { ...DEFAULT_CRON_SCHEDULER_CONFIG, ...config };
+        this.notepad = new JobNotepadStore(path.join(path.dirname(this.config.persistPath), 'notepads'));
+    }
+    /** Directory of isolated per-job notepad files (`<cron-root>/notepads`). */
+    get notepadDir() {
+        return path.join(path.dirname(this.config.persistPath), 'notepads');
     }
     // ==========================================================================
     // Lifecycle
@@ -267,6 +274,8 @@ export class CronScheduler extends EventEmitter {
     async addJob(params) {
         const id = crypto.randomUUID();
         const now = new Date();
+        const continuity = params.continuity === undefined ? undefined : validateContinuity(params.continuity);
+        const seededNotes = typeof continuity === 'object' ? continuity.notes : undefined;
         const job = {
             id,
             name: params.name,
@@ -285,6 +294,7 @@ export class CronScheduler extends EventEmitter {
             sessionTarget: params.sessionTarget,
             preCheck: params.preCheck,
             then: params.then,
+            continuity: persistableContinuity(continuity),
         };
         // Resolve 'current' session target to concrete session ID at creation time
         if (job.sessionTarget === 'current') {
@@ -292,6 +302,9 @@ export class CronScheduler extends EventEmitter {
         }
         // Calculate next run
         job.nextRunAt = this.calculateNextRun(job);
+        if (seededNotes && isContinuityEnabled(job.continuity)) {
+            await this.notepad.replaceNotes(id, seededNotes);
+        }
         this.jobs.set(id, job);
         await this.persistJobs();
         if (job.enabled && this.running) {
@@ -307,11 +320,23 @@ export class CronScheduler extends EventEmitter {
         const job = this.jobs.get(jobId);
         if (!job)
             return null;
-        // Cancel existing timer
+        const { continuity: inputContinuity, ...rest } = updates;
+        const continuity = inputContinuity === undefined ? undefined : validateContinuity(inputContinuity);
+        const next = { ...job, ...rest };
+        if (continuity !== undefined)
+            next.continuity = persistableContinuity(continuity);
+        // Validate scheduling before writing notes; retain the live job/timer on failure.
+        this.calculateNextRun(next);
+        if (continuity !== undefined) {
+            const seededNotes = typeof continuity === 'object' ? continuity.notes : undefined;
+            if (seededNotes && isContinuityEnabled(next.continuity)) {
+                await this.notepad.replaceNotes(jobId, seededNotes);
+            }
+        }
         this.cancelJobTimer(jobId);
-        // Apply updates
-        Object.assign(job, updates);
-        // Recalculate next run
+        Object.assign(job, rest);
+        if (continuity !== undefined)
+            job.continuity = next.continuity;
         job.nextRunAt = this.calculateNextRun(job);
         // Reschedule if enabled
         if (job.enabled && this.running) {
@@ -329,6 +354,12 @@ export class CronScheduler extends EventEmitter {
             return false;
         this.cancelJobTimer(jobId);
         this.jobs.delete(jobId);
+        try {
+            await this.notepad.clear(jobId);
+        }
+        catch (error) {
+            logger.warn('Cron job removed but its notepad could not be cleared', { jobId, error: String(error) });
+        }
         await this.persistJobs();
         this.emit('job:deleted', jobId);
         return true;

package/dist/scheduler/job-notepad.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Per-job bounded continuity store (Hermes-inspired cron notepad).
+ *
+ * Isolated JSON files under `<cron-root>/notepads/<jobId>.json`, written
+ * atomically (0600): 16 KiB per value, 128-char keys, 64 KiB per serialized
+ * record. Mutations use an exclusive per-job lock across local processes.
+ * Contention requires retry; abandoned locks require operator inspection and
+ * are never stolen. Invalid/corrupt records are preserved for inspection.
+ */
+export declare const MAX_VALUE_BYTES: number;
+export declare const MAX_KEY_CHARS = 128;
+export declare const MAX_JOB_TOTAL_BYTES: number;
+export declare const MAX_LAST_OUTPUT_BYTES: number;
+export type ContinuityFlag = boolean | {
+    enabled?: boolean;
+    notes?: Record<string, string>;
+};
+export interface JobNotepadRecord {
+    notes: Record<string, string>;
+    /** Most recent non-empty successful output that was saved. */
+    lastSuccessfulOutput?: string;
+    updatedAt: string;
+}
+export declare class JobNotepadBusyError extends Error {
+    constructor();
+}
+/** Validate operator/tool input before changing jobs or writing any notes. */
+export declare function validateContinuity(value: unknown): ContinuityFlag;
+export declare function isContinuityEnabled(continuity: ContinuityFlag | undefined): boolean;
+/** Persist the opt-in flag only — notes live in the notepad file, not jobs.json. */
+export declare function persistableContinuity(continuity: ContinuityFlag | undefined): boolean | {
+    enabled: boolean;
+} | undefined;
+export declare function defaultNotepadDir(): string;
+export declare function utf8ByteLength(value: string): number;
+export declare function sanitizeJobId(jobId: string): string;
+export declare function truncateUtf8(value: string, maxBytes: number): string;
+export declare function notesByteTotal(notes: Record<string, string>): number;
+export declare function assertNotesWithinCaps(notes: unknown): asserts notes is Record<string, string>;
+export declare class JobNotepadStore {
+    private readonly dir;
+    constructor(dir?: string);
+    fileFor(jobId: string): string;
+    load(jobId: string): Promise<JobNotepadRecord>;
+    setNote(jobId: string, key: string, value: string): Promise<JobNotepadRecord>;
+    replaceNotes(jobId: string, notes: Record<string, string>): Promise<JobNotepadRecord>;
+    getNote(jobId: string, key: string): Promise<string | undefined>;
+    deleteNote(jobId: string, key: string): Promise<boolean>;
+    listNotes(jobId: string): Promise<Array<{
+        key: string;
+        value: string;
+    }>>;
+    /**
+     * Record the last *successful* job output. Truncates to the per-value and
+     * serialized per-job caps. Storage errors are reported to the caller.
+     * Empty output leaves the previous non-empty successful output in place.
+     */
+    saveLastSuccessfulOutput(jobId: string, output: string): Promise<void>;
+    /** Missing files are a no-op; existing files share writer exclusion. */
+    clear(jobId: string): Promise<void>;
+    /**
+     * Prompt section for this job. Empty notepad MUST return '' so jobs that
+     * never use continuity keep a byte-identical agent prompt.
+     */
+    renderSection(jobId: string): Promise<string>;
+    private commitNotes;
+    private write;
+    private withMutationLock;
+}