@a1hvdy/cc-openclaw 0.17.0 → 0.18.1

package/dist/src/lifecycle/safe-restart.d.ts

@@ -1,99 +0,0 @@
-/**
- * safe-restart — in-process gateway restart that preserves the current
- * Telegram session.
- *
- * Pre-Execution Decision (PRP_v2 §Pre-Execution Decisions, locked):
- *   Path: --safe-current-session flag (in-process).
- *   Rationale: avoids tmux zombie risk (Risk Register row 3); cleaner state
- *   model; tmux-detach remains available as a secondary path (v0.17 deferred).
- *
- * Usage (programmatic):
- *   const restart = new SafeRestart({ sessionId: 'my-session' });
- *   const result = await restart.run();
- *
- * Usage (CLI flag):
- *   cc-openclaw --safe-current-session [--session-id <id>]
- *   Parsed in src/cli/index.ts and forwarded here.
- *
- * Self-survival contract:
- *   When OpenClaw triggers a gateway restart while a Telegram session is
- *   active, the session must NOT fire a sub-agent "self-survival" turn. This
- *   module registers a SIGTERM handler that:
- *     1. Flushes in-flight state (EventBus drain-wait up to FLUSH_TIMEOUT_MS).
- *     2. Marks the named session as restart-pending in the session registry.
- *     3. Emits a 'safe-restart.initiated' telemetry event.
- *     4. Returns "in-process" — the gateway respawner picks this signal up and
- *        skips the self-survival sub-agent path.
- *
- * SecondaryPath — tmux-detach:
- *   See scripts/gateway-detach.sh. NOT the default per locked decision above.
- *   SafeRestart.run() returns { mode: 'not-implemented' } when forced into
- *   tmux-detach mode so callers handle it cleanly without crashing.
- */
-import { EventBus } from '../observability/event-bus.js';
-export type RestartMode = 'in-process' | 'tmux-detach';
-export interface SafeRestartOptions {
-    /** Session ID that must survive the restart. */
-    sessionId: string;
-    /**
-     * Restart mode. Defaults to 'in-process' per locked PRP_v2 decision.
-     * 'tmux-detach' is a stub that returns { mode: 'not-implemented' }.
-     */
-    mode?: RestartMode;
-    /** EventBus to emit telemetry events. If omitted, a private bus is used. */
-    bus?: EventBus;
-    /**
-     * Maximum milliseconds to wait for in-flight state flush before proceeding.
-     * Default: 2000.
-     */
-    flushTimeoutMs?: number;
-}
-export interface SafeRestartResult {
-    /** 'in-process' when restart succeeded in-process. */
-    mode: 'in-process' | 'not-implemented';
-    sessionId: string;
-    /** ISO timestamp of when restart was initiated. */
-    initiatedAt: string;
-}
-export declare class SafeRestart {
-    private readonly sessionId;
-    private readonly mode;
-    private readonly bus;
-    private readonly flushTimeoutMs;
-    constructor(opts: SafeRestartOptions);
-    /**
-     * Execute the safe-restart sequence.
-     *
-     * In-process path:
-     *   1. Wait up to flushTimeoutMs for in-flight state to drain.
-     *   2. Emit 'safe-restart.initiated' telemetry.
-     *   3. Return { mode: 'in-process', ... }.
-     *
-     * Tmux-detach path:
-     *   Returns { mode: 'not-implemented', ... } — deferred to v0.17.
-     *   See scripts/gateway-detach.sh for the secondary path stub.
-     */
-    run(): Promise<SafeRestartResult>;
-    /**
-     * Wait for in-flight state to drain. If flush takes longer than
-     * flushTimeoutMs, we proceed anyway — restart is more important than
-     * waiting indefinitely.
-     */
-    private flushInFlight;
-    /**
-     * Give the EventBus a single microtask tick to deliver any pending
-     * synchronous events before we mark the session as restart-pending.
-     */
-    private drainEventBus;
-    private emitTelemetry;
-}
-/**
- * Returns true when the --safe-current-session flag is present in argv OR
- * when OPENCLAW_SAFE_CURRENT_SESSION=1 is set in the environment.
- * Used by src/cli/index.ts to decide whether to run the safe-restart path.
- */
-export declare function isSafeCurrentSessionRequested(argv?: string[]): boolean;
-/**
- * Parse --session-id <value> from argv. Returns undefined when not present.
- */
-export declare function parseSessionIdFromArgv(argv?: string[]): string | undefined;

package/dist/src/lifecycle/safe-restart.js

@@ -1,132 +0,0 @@
-/**
- * safe-restart — in-process gateway restart that preserves the current
- * Telegram session.
- *
- * Pre-Execution Decision (PRP_v2 §Pre-Execution Decisions, locked):
- *   Path: --safe-current-session flag (in-process).
- *   Rationale: avoids tmux zombie risk (Risk Register row 3); cleaner state
- *   model; tmux-detach remains available as a secondary path (v0.17 deferred).
- *
- * Usage (programmatic):
- *   const restart = new SafeRestart({ sessionId: 'my-session' });
- *   const result = await restart.run();
- *
- * Usage (CLI flag):
- *   cc-openclaw --safe-current-session [--session-id <id>]
- *   Parsed in src/cli/index.ts and forwarded here.
- *
- * Self-survival contract:
- *   When OpenClaw triggers a gateway restart while a Telegram session is
- *   active, the session must NOT fire a sub-agent "self-survival" turn. This
- *   module registers a SIGTERM handler that:
- *     1. Flushes in-flight state (EventBus drain-wait up to FLUSH_TIMEOUT_MS).
- *     2. Marks the named session as restart-pending in the session registry.
- *     3. Emits a 'safe-restart.initiated' telemetry event.
- *     4. Returns "in-process" — the gateway respawner picks this signal up and
- *        skips the self-survival sub-agent path.
- *
- * SecondaryPath — tmux-detach:
- *   See scripts/gateway-detach.sh. NOT the default per locked decision above.
- *   SafeRestart.run() returns { mode: 'not-implemented' } when forced into
- *   tmux-detach mode so callers handle it cleanly without crashing.
- */
-import { EventBus } from '../observability/event-bus.js';
-// ── Constants ─────────────────────────────────────────────────────────────────
-const FLUSH_TIMEOUT_MS = 2_000;
-const ENV_FLAG = 'OPENCLAW_SAFE_CURRENT_SESSION';
-// ── SafeRestart class ─────────────────────────────────────────────────────────
-export class SafeRestart {
-    sessionId;
-    mode;
-    bus;
-    flushTimeoutMs;
-    constructor(opts) {
-        this.sessionId = opts.sessionId;
-        this.mode = opts.mode ?? 'in-process';
-        this.bus = opts.bus ?? new EventBus();
-        this.flushTimeoutMs = opts.flushTimeoutMs ?? FLUSH_TIMEOUT_MS;
-    }
-    /**
-     * Execute the safe-restart sequence.
-     *
-     * In-process path:
-     *   1. Wait up to flushTimeoutMs for in-flight state to drain.
-     *   2. Emit 'safe-restart.initiated' telemetry.
-     *   3. Return { mode: 'in-process', ... }.
-     *
-     * Tmux-detach path:
-     *   Returns { mode: 'not-implemented', ... } — deferred to v0.17.
-     *   See scripts/gateway-detach.sh for the secondary path stub.
-     */
-    async run() {
-        const initiatedAt = new Date().toISOString();
-        if (this.mode === 'tmux-detach') {
-            // Secondary path — deferred to v0.17. Return not-implemented cleanly.
-            this.emitTelemetry('safe-restart.not-implemented', initiatedAt);
-            return { mode: 'not-implemented', sessionId: this.sessionId, initiatedAt };
-        }
-        // In-process path.
-        await this.flushInFlight();
-        this.emitTelemetry('safe-restart.initiated', initiatedAt);
-        return { mode: 'in-process', sessionId: this.sessionId, initiatedAt };
-    }
-    // ── Private helpers ─────────────────────────────────────────────────────────
-    /**
-     * Wait for in-flight state to drain. If flush takes longer than
-     * flushTimeoutMs, we proceed anyway — restart is more important than
-     * waiting indefinitely.
-     */
-    async flushInFlight() {
-        await Promise.race([
-            this.drainEventBus(),
-            new Promise((resolve) => setTimeout(resolve, this.flushTimeoutMs)),
-        ]);
-    }
-    /**
-     * Give the EventBus a single microtask tick to deliver any pending
-     * synchronous events before we mark the session as restart-pending.
-     */
-    async drainEventBus() {
-        // EventBus.emit() is synchronous; a single await tick ensures any
-        // callers that queued events via Promise.resolve() have run.
-        await Promise.resolve();
-    }
-    emitTelemetry(event, initiatedAt) {
-        // EventBus EventMap is typed — we use the raw emit approach for
-        // extensibility events not yet in the typed map. A typed entry will
-        // be added to EventMap when the telemetry consumer (agent-streaming)
-        // lands in Phase 2.
-        try {
-            this.bus.emit(event, {
-                sessionId: this.sessionId,
-                initiatedAt,
-                mode: this.mode,
-            });
-        }
-        catch {
-            // Telemetry is best-effort; never block restart on a bus error.
-        }
-    }
-}
-// ── CLI flag helpers ──────────────────────────────────────────────────────────
-/**
- * Returns true when the --safe-current-session flag is present in argv OR
- * when OPENCLAW_SAFE_CURRENT_SESSION=1 is set in the environment.
- * Used by src/cli/index.ts to decide whether to run the safe-restart path.
- */
-export function isSafeCurrentSessionRequested(argv = process.argv) {
-    if (process.env[ENV_FLAG] === '1')
-        return true;
-    return argv.includes('--safe-current-session');
-}
-/**
- * Parse --session-id <value> from argv. Returns undefined when not present.
- */
-export function parseSessionIdFromArgv(argv = process.argv) {
-    const idx = argv.indexOf('--session-id');
-    if (idx !== -1 && idx + 1 < argv.length) {
-        return argv[idx + 1];
-    }
-    return undefined;
-}
-//# sourceMappingURL=safe-restart.js.map

package/dist/src/lifecycle/safe-restart.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"safe-restart.js","sourceRoot":"","sources":["../../../src/lifecycle/safe-restart.ts"],"names":[],"mappings":"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"}