@made-by-moonlight/athene-core 0.9.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Composio, Inc.
+Copyright (c) 2026 slievr (Athene fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# @made-by-moonlight/athene-core
+
+Core services, types, and configuration for the Athene system.
+
+## What's Here
+
+- **`src/types.ts`** — All TypeScript interfaces (Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal, Session, events)
+- **`src/services/`** — Core services (SessionManager, LifecycleManager, PluginRegistry)
+- **`src/config.ts`** — Configuration loading + Zod schemas
+- **`src/utils/`** — Shared utilities (shell escaping, metadata parsing, etc.)
+
+## Key Files
+
+### `src/types.ts` — The Source of Truth
+
+Every interface the system uses is defined here. If you're working on any part of the orchestrator, start by reading this file.
+
+**Main interfaces:**
+
+- `Runtime` — where sessions execute (tmux on Unix, `process` / ConPTY via node-pty on Windows, docker, k8s)
+- `Agent` — AI coding tool adapter (claude-code, codex, aider)
+- `Workspace` — code isolation (worktree, clone)
+- `Tracker` — issue tracking (GitHub Issues, Linear)
+- `SCM` — PR/CI/reviews (GitHub, GitLab)
+- `Notifier` — push notifications (desktop, Slack, webhook)
+- `Terminal` — human interaction UI (iTerm2, web)
+- `Session` — running agent instance (state, metadata, handles)
+- `OrchestratorEvent` — events emitted by lifecycle manager
+- `PluginModule` — what every plugin exports
+
+### `src/services/session-manager.ts` — Session CRUD
+
+Handles session lifecycle:
+
+- `spawn(config)` — create new session (workspace + runtime + agent)
+- `list(projectId?)` — list all sessions
+- `get(sessionId)` — get session details
+- `kill(sessionId)` — terminate session
+- `cleanup(projectId?)` — kill completed/merged sessions
+- `send(sessionId, message)` — send message to agent
+
+**Data flow in `spawn()`:**
+
+1. Load project config
+2. **Validate issue exists** via `Tracker.getIssue()` (if issueId provided, fails-fast if not found)
+3. Reserve session ID
+4. Determine branch name
+5. Create workspace via `Workspace.create()`
+6. Generate prompt via `Tracker.generatePrompt()`
+7. Build layered worker prompt via `buildPrompt()` into `systemPrompt` + `taskPrompt`
+8. Persist `systemPromptFile` for the session and, for OpenCode workers, write `OPENCODE_CONFIG`
+9. Build launch command via `Agent.getLaunchCommand()`
+10. Create runtime session via `Runtime.create()`
+11. Run `Agent.postLaunchSetup()` (optional)
+12. Write metadata file
+13. Return Session object
+
+**Note:** If issue validation fails (not found, auth error), spawn fails before creating any resources (no workspace, no runtime, no session ID). This prevents spawning sessions with broken issue references.
+Worker sessions keep persistent instructions in the prompt file. OpenCode workers consume that file through `OPENCODE_CONFIG`, while OpenCode orchestrators continue to project their system prompt into workspace `AGENTS.md`.
+
+### `src/services/lifecycle-manager.ts` — State Machine + Reactions
+
+Polls sessions, detects state changes, triggers reactions:
+
+**State machine:**
+
+```
+spawning → working → pr_open → ci_failed/review_pending/approved → mergeable → merged
+```
+
+**Reactions:**
+
+- `ci-failed` → send fix prompt to agent
+- `changes-requested` → send review comments to agent
+- `approved-and-green` → notify human (or auto-merge)
+- `agent-stuck` → notify human
+
+**Polling loop:**
+
+1. For each session: check agent activity state (`Agent.getActivityState()`)
+2. If PR exists: check CI status (`SCM.getCISummary()`), review state (`SCM.getReviewDecision()`)
+3. Update session status based on state
+4. Trigger reactions if state changed
+5. Emit events
+
+### `src/services/plugin-registry.ts` — Plugin Discovery + Loading
+
+Loads plugins and provides access to them:
+
+- `register(plugin, config?)` — register a plugin instance
+- `get<T>(slot, name)` — get plugin by slot + name
+- `list(slot)` — list all plugins for a slot
+- `loadBuiltins(config?)` — load built-in plugins (runtime-tmux, agent-claude-code, etc.)
+- `loadFromConfig(config)` — load built-ins today; external plugin descriptors are the marketplace extension point
+
+**Built-in plugins** (loaded by default):
+
+- runtime-tmux, runtime-process
+- agent-claude-code, agent-codex, agent-aider, agent-cursor, agent-kimicode, agent-opencode
+- workspace-worktree, workspace-clone
+- tracker-github, tracker-linear, tracker-gitlab
+- scm-github, scm-gitlab
+- notifier-desktop, notifier-discord, notifier-slack, notifier-composio, notifier-openclaw, notifier-webhook
+- terminal-iterm2, terminal-web
+
+### `src/config.ts` — Configuration Loading
+
+Loads and validates `agent-orchestrator.yaml`:
+
+**Main config sections:**
+
+- Runtime data paths are auto-derived from the config location under `~/.agent-orchestrator/{hash}-{projectId}/`
+- `port` — web dashboard port (default 3000, set different values for multiple projects)
+- `terminalPort` — terminal WebSocket port (auto-detected if not set)
+- `directTerminalPort` — direct terminal WebSocket port (auto-detected if not set)
+- `defaults` — default plugins (runtime, agent, workspace, notifiers)
+- `plugins` — installer-managed external plugin descriptors (registry, npm, or local)
+- `projects` — per-project config (repo, path, branch, symlinks, reactions, agentRules)
+- `notifiers` — notification channel config (Slack webhooks, etc.)
+- `notificationRouting` — which notifiers get which priority events
+- `reactions` — auto-response config (ci-failed, changes-requested, approved-and-green, etc.)
+
+**Zod schemas** validate all config at load time.
+
+## Common Tasks
+
+### Adding a Field to Session
+
+1. Edit `src/types.ts` → `Session` interface
+2. Edit `src/services/session-manager.ts` → initialize field in `spawn()`
+3. Rebuild: `pnpm --filter @made-by-moonlight/athene-core build`
+
+### Adding an Event Type
+
+1. Edit `src/types.ts` → `EventType` union
+2. Emit the event: `eventEmitter.emit()` in relevant service
+3. Add reaction handler (optional): `src/services/lifecycle-manager.ts`
+
+### Adding a Reaction
+
+1. Edit `src/services/lifecycle-manager.ts` → add handler function
+2. Wire it up in the polling loop
+3. Add config schema in `src/config.ts` if new reaction type
+
+### Feedback Tools (v1)
+
+`@made-by-moonlight/athene-core` exports two structured feedback tool contracts:
+
+- `bug_report`
+- `improvement_suggestion`
+
+Both share the same required input fields:
+
+- `title`
+- `body`
+- `evidence` (array of strings)
+- `session`
+- `source`
+- `confidence` (0..1)
+
+Example:
+
+```ts
+import { FEEDBACK_TOOL_NAMES, FeedbackReportStore, getFeedbackReportsDir } from "@made-by-moonlight/athene-core";
+
+const reportsDir = getFeedbackReportsDir(configPath, projectPath);
+const store = new FeedbackReportStore(reportsDir);
+
+const saved = store.persist(FEEDBACK_TOOL_NAMES.BUG_REPORT, {
+  title: "SSO login loop",
+  body: "Google SSO redirects back to /login repeatedly.",
+  evidence: ["trace_id=abc123", "screenshot: login-loop.png"],
+  session: "ao-22",
+  source: "agent",
+  confidence: 0.84,
+});
+```
+
+Storage format:
+
+- Reports are persisted under `~/.agent-orchestrator/{hash}-{projectId}/feedback-reports`
+- Each report is a typed key=value file (`report_<timestamp>_<id>.kv`) for easy inspection
+- A deterministic dedupe key (`sha256`, 16 hex chars) is generated from normalized tool+content
+
+Migration notes:
+
+- No migration needed for existing AO installs
+- The `feedback-reports` directory is created lazily on first persisted report
+
+## Testing
+
+```bash
+# Run all core tests
+pnpm --filter @made-by-moonlight/athene-core test
+
+# Run in watch mode
+pnpm --filter @made-by-moonlight/athene-core test -- --watch
+
+# Run specific test
+pnpm --filter @made-by-moonlight/athene-core test -- session-manager.test.ts
+```
+
+Tests are in `src/__tests__/`:
+
+- `session-manager.test.ts` — session CRUD, spawn, cleanup
+- `lifecycle-manager.test.ts` — state machine, reactions
+- `plugin-registry.test.ts` — plugin loading, resolution
+- `tmux.test.ts` — tmux utility functions (not a plugin test)
+- `prompt-builder.test.ts` — prompt generation utilities
+
+## Building
+
+```bash
+# Build core
+pnpm --filter @made-by-moonlight/athene-core build
+
+# Typecheck
+pnpm --filter @made-by-moonlight/athene-core typecheck
+```
+
+This package is a dependency of all other packages. Build it first if working on the codebase.
+
+## Architecture Notes
+
+**Why flat metadata files?**
+
+- Debuggability: `cat ~/.agent-orchestrator/<hash>-my-app/sessions/app-3` shows full state
+- No database dependency (survives crashes, easy to inspect)
+- Backwards-compatible with bash script orchestrator
+
+**Why polling instead of webhooks?**
+
+- Simpler (no webhook setup, no ngrok for local dev)
+- Works offline (CI/review state is fetched, not pushed)
+- Survives orchestrator restarts (no missed events)
+
+**Why plugin slots?**
+
+- Swappability: use tmux on Linux/macOS, `process` (ConPTY) on Windows, docker in CI, k8s in prod — same agent/workspace stack across all of them
+- Testability: mock plugins for tests
+- Extensibility: users can add custom plugins (e.g., company-specific notifier)

package/dist/activity-events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Activity event logging — write API.
+ *
+ * recordActivityEvent() is synchronous and best-effort: it never throws.
+ * If the DB is unavailable or a write fails, the event is dropped and
+ * droppedEventCount is incremented.
+ *
+ * droppedEventCount is process-local. Events dropped in other processes
+ * (web server, lifecycle manager) are not reflected here.
+ */
+export type ActivityEventSource = "lifecycle" | "session-manager" | "api" | "ui" | "scm" | "runtime" | "agent" | "tracker" | "workspace" | "notifier" | "reaction" | "report-watcher" | "cli" | "config" | "plugin-registry" | "migration" | "recovery";
+export type ActivityEventKind = "session.spawn_started" | "session.spawned" | "session.spawn_failed" | "session.spawn_step_failed" | "session.killed" | "session.kill_started" | "session.send_failed" | "session.restore_failed" | "session.restore_fallback" | "session.rollback_started" | "session.rollback_step_failed" | "session.workspace_hooks_failed" | "session.cleanup_error" | "session.orchestrator_conflict" | "runtime.lost_detected" | "runtime.lost_persist_failed" | "runtime.destroy_failed" | "workspace.destroy_failed" | "agent.opencode_purge_failed" | "tracker.issue_fetch_failed" | "tracker.generate_prompt_failed" | "metadata.corrupt_detected" | "activity.transition" | "lifecycle.transition" | "ci.failing" | "review.pending" | "scm.batch_enrich_failed" | "scm.detect_pr_succeeded" | "scm.detect_pr_failed" | "scm.review_fetch_failed" | "scm.poll_pr_failed" | "runtime.probe_failed" | "agent.process_probe_failed" | "agent.activity_probe_failed" | "scm.gh_unavailable" | "scm.batch_enrich_pr_failed" | "scm.ci_summary_failclosed" | "workspace.post_create_failed" | "workspace.branch_collision" | "workspace.destroy_fell_back" | "workspace.corrupt_clone_skipped" | "tracker.dep_missing" | "tracker.api_timeout" | "notifier.auth_failed" | "notifier.unreachable" | "notifier.rate_limited" | "notifier.dep_missing" | "reaction.escalated" | "reaction.send_to_agent_failed" | "reaction.action_succeeded" | "session.auto_cleanup_deferred" | "session.auto_cleanup_completed" | "session.auto_cleanup_failed" | "lifecycle.poll_failed" | "detecting.escalated" | "notification.delivery_failed" | "notification.target_missing" | "report_watcher.triggered" | "config.project_resolve_failed" | "config.project_malformed" | "config.project_invalid" | "config.migrated" | "plugin-registry.load_failed" | "plugin-registry.validation_failed" | "plugin-registry.specifier_failed" | "migration.blocked" | "migration.project_failed" | "migration.rename_failed" | "migration.completed" | "migration.rollback_skipped" | "api.webhook_unverified" | "api.webhook_rejected" | "api.webhook_received" | "api.webhook_failed" | "ui.terminal_connected" | "ui.terminal_disconnected" | "ui.terminal_heartbeat_lost" | "ui.terminal_pty_lost" | "ui.terminal_protocol_error" | "ui.session_broadcast_failed" | "recovery.session_failed" | "recovery.action_failed" | "api.agent_report.session_not_found" | "api.agent_report.transition_rejected" | "api.agent_report.apply_failed";
+export type ActivityEventLevel = "debug" | "info" | "warn" | "error";
+export interface ActivityEventInput {
+    projectId?: string;
+    sessionId?: string;
+    source: ActivityEventSource | string;
+    kind: ActivityEventKind | string;
+    level?: ActivityEventLevel;
+    summary: string;
+    data?: Record<string, unknown>;
+}
+export interface ActivityEvent {
+    id: number;
+    tsEpoch: number;
+    ts: string;
+    projectId: string | null;
+    sessionId: string | null;
+    source: string;
+    kind: string;
+    level: string;
+    summary: string;
+    data: string | null;
+    rank?: number;
+}
+/** Number of events dropped due to DB errors in this process. */
+export declare function droppedEventCount(): number;
+/**
+ * Record an activity event. Synchronous, best-effort — never throws.
+ */
+export declare function recordActivityEvent(event: ActivityEventInput): void;
+//# sourceMappingURL=activity-events.d.ts.map

package/dist/activity-events.d.ts.map

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

package/dist/activity-events.js

@@ -0,0 +1,192 @@
+import { getDb } from './events-db.js';
+
+/**
+ * Activity event logging — write API.
+ *
+ * recordActivityEvent() is synchronous and best-effort: it never throws.
+ * If the DB is unavailable or a write fails, the event is dropped and
+ * droppedEventCount is incremented.
+ *
+ * droppedEventCount is process-local. Events dropped in other processes
+ * (web server, lifecycle manager) are not reflected here.
+ */
+let _droppedEventCount = 0;
+let _lastPruneMs = 0;
+const PRUNE_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+const RETENTION_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const PRUNE_BATCH_SIZE = 1000;
+/** Number of events dropped due to DB errors in this process. */
+function droppedEventCount() {
+    return _droppedEventCount;
+}
+function pruneOldEvents(db, cutoff) {
+    db?.prepare(`DELETE FROM activity_events
+       WHERE rowid IN (
+         SELECT rowid FROM activity_events WHERE ts_epoch < ? LIMIT ?
+       )`).run(cutoff, PRUNE_BATCH_SIZE);
+}
+// Patterns that indicate sensitive field names
+const SENSITIVE_KEY_RE = /token|password|secret|authorization|cookie|api[-_]?key/i;
+// URL credentials: https://token@host or http://user:pass@host.
+// Linear scan — find :// then scan forward for the next @ before a path
+// separator or whitespace. O(n) worst case, no regex backtracking, no length
+// limits. Replaces the previous CREDENTIAL_URL_RE which either ReDoS'd
+// (unbounded quantifier) or missed >200-char userinfo (bounded quantifier).
+function redactCredentialUrls(input) {
+    let result = input;
+    let offset = 0;
+    while (offset < result.length) {
+        const proto = result.indexOf("://", offset);
+        if (proto === -1)
+            break;
+        // Only match http:// or https:// (case-insensitive, matching old /gi flag)
+        if (proto < 4) {
+            offset = proto + 3;
+            continue;
+        }
+        const schemeEnd = result.slice(Math.max(0, proto - 5), proto).toLowerCase();
+        if (!schemeEnd.endsWith("http") && !schemeEnd.endsWith("https")) {
+            offset = proto + 3;
+            continue;
+        }
+        let cursor = proto + 3;
+        while (cursor < result.length) {
+            const ch = result.charCodeAt(cursor);
+            // Space/control chars or '/' mean no '@' is coming in userinfo
+            if (ch <= 0x20 || ch === 0x2f)
+                break;
+            if (ch === 0x40) {
+                // '@' found — redact everything between :// and @
+                // Lowercase the scheme to match the old /gi regex behavior
+                const before = result.slice(0, proto + 3).toLowerCase();
+                const suffix = result.slice(cursor);
+                result = before + "[redacted]" + suffix;
+                offset = proto + 3 + "[redacted]".length + 1;
+                break;
+            }
+            cursor++;
+        }
+        // No '@' found — not a credential URL, move past this ://
+        if (cursor >= result.length ||
+            result.charCodeAt(cursor) <= 0x20 ||
+            result.charCodeAt(cursor) === 0x2f) {
+            offset = proto + 3;
+        }
+    }
+    return result;
+}
+// Per-string-value cap. The whole-data 16 KB cap still applies on top of this;
+// truncating individual strings limits blast radius if a pattern below misses a
+// new token format and a long error message gets pasted in.
+const STRING_VALUE_MAX_CHARS = 500;
+// Token-shape patterns matched against ANY string value, not just keys.
+// Order: more-specific first. Replacement strings preserve the prefix where
+// the prefix itself is informative (e.g. "Bearer [redacted]" so RCA can still
+// see this was a bearer-auth failure).
+//
+// SENSITIVE_KEY_RE above redacts entire values under sensitive *key* names;
+// these patterns redact token-shaped *substrings* anywhere — including under
+// keys like `message` and `errorMessage`, which are the leak vector flagged
+// in PR #1620 review (data column is FTS5-indexed in events-db.ts).
+const TOKEN_PATTERNS = [
+    // Bearer auth headers (also catches JWTs prefixed with Bearer)
+    [/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi, "Bearer [redacted]"],
+    // GitHub Personal Access Tokens — classic (ghp_/gho_/ghu_/ghs_/ghr_)
+    [/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "[redacted]"],
+    // GitHub fine-grained PATs
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "[redacted]"],
+    // OpenAI / Anthropic sk- keys (incl. sk-proj-, sk-svcacct-, sk-ant-)
+    [/\bsk-(?:ant-)?(?:proj-|svcacct-)?[A-Za-z0-9_-]{16,}\b/g, "[redacted]"],
+    // Slack tokens (xoxb-, xoxp-, xoxa-, xoxr-, xoxs-)
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, "[redacted]"],
+    // AWS access key IDs (16 trailing chars exactly per AWS spec)
+    [/\bAKIA[0-9A-Z]{16}\b/g, "[redacted]"],
+    // JWTs — three base64url segments, eyJ prefix on header
+    [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "[redacted]"],
+    // ENV-style assignments: MY_API_TOKEN=value, GITHUB_SECRET=..., etc.
+    // Scoped to ALL_CAPS keys containing a sensitive word so prose like
+    // "the message=hello" doesn't redact.
+    [
+        /\b([A-Z][A-Z0-9_]*(?:TOKEN|PASSWORD|SECRET|AUTHORIZATION|COOKIE|API_KEY|APIKEY)[A-Z0-9_]*)=([^\s"'`]{6,})/g,
+        "$1=[redacted]",
+    ],
+];
+function sanitizeString(value) {
+    let cleaned = redactCredentialUrls(value);
+    for (const [pattern, replacement] of TOKEN_PATTERNS) {
+        cleaned = cleaned.replace(pattern, replacement);
+    }
+    if (cleaned.length > STRING_VALUE_MAX_CHARS) {
+        cleaned = `${cleaned.slice(0, STRING_VALUE_MAX_CHARS - 3)}...`;
+    }
+    return cleaned;
+}
+function sanitizeValue(value, seen) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "string")
+        return sanitizeString(value);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeValue(item, seen));
+    }
+    const cleaned = {};
+    for (const [k, v] of Object.entries(value)) {
+        cleaned[k] = SENSITIVE_KEY_RE.test(k) ? "[redacted]" : sanitizeValue(v, seen);
+    }
+    return cleaned;
+}
+function sanitizeData(data) {
+    const cleaned = sanitizeValue(data, new WeakSet());
+    let json;
+    try {
+        json = JSON.stringify(cleaned);
+    }
+    catch {
+        return undefined;
+    }
+    // Reject if over 16 KB after sanitization (slicing would produce malformed JSON)
+    if (json.length > 16 * 1024) {
+        return undefined;
+    }
+    return json;
+}
+function sanitizeSummary(summary) {
+    if (summary.length <= 500)
+        return summary;
+    return `${summary.slice(0, 497)}...`;
+}
+/**
+ * Record an activity event. Synchronous, best-effort — never throws.
+ */
+function recordActivityEvent(event) {
+    try {
+        const db = getDb();
+        if (!db) {
+            _droppedEventCount++;
+            return;
+        }
+        const now = Date.now();
+        const ts = new Date(now).toISOString();
+        const summary = sanitizeSummary(event.summary);
+        const data = event.data ? sanitizeData(event.data) : undefined;
+        db.prepare(`INSERT INTO activity_events
+        (ts_epoch, ts, project_id, session_id, source, type, log_level, summary, data)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(now, ts, event.projectId ?? null, event.sessionId ?? null, event.source, event.kind, event.level ?? "info", summary, data ?? null);
+        // Periodically purge old events so long-lived processes don't grow the DB indefinitely
+        if (now - _lastPruneMs >= PRUNE_INTERVAL_MS) {
+            _lastPruneMs = now;
+            pruneOldEvents(db, now - RETENTION_MS);
+        }
+    }
+    catch {
+        _droppedEventCount++;
+    }
+}
+
+export { droppedEventCount, recordActivityEvent };
+//# sourceMappingURL=activity-events.js.map

package/dist/activity-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-events.js","sources":["../src/activity-events.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/activity-log.d.ts

@@ -0,0 +1,71 @@
+import type { ActivityState, ActivityLogEntry, ActivityDetection } from "./types.js";
+/**
+ * @deprecated Actionable states no longer decay on wallclock. Retained until
+ * the activity-reducer cleanup removes the old activity-log module.
+ */
+export declare const ACTIVITY_INPUT_STALENESS_MS: number;
+/**
+ * Get the path to the activity JSONL log for a session.
+ * Location: `{workspacePath}/.ao/activity.jsonl`
+ */
+export declare function getActivityLogPath(workspacePath: string): string;
+/**
+ * Append an activity observation to the session's JSONL log.
+ * Creates the `.ao/` directory if it doesn't exist.
+ */
+export declare function appendActivityEntry(workspacePath: string, state: ActivityState, source: "terminal" | "native" | "hook", trigger?: string): Promise<void>;
+/**
+ * Read the last activity entry from the session's JSONL log.
+ * Returns the parsed entry with the file's modification time, or null if
+ * the file doesn't exist or is empty.
+ */
+export declare function readLastActivityEntry(workspacePath: string): Promise<{
+    entry: ActivityLogEntry;
+    modifiedAt: Date;
+} | null>;
+/**
+ * Check the AO activity JSONL for actionable states only.
+ *
+ * Only returns `waiting_input`/`blocked`.
+ * Non-critical states (`active`, `ready`, `idle`) always return `null` so
+ * callers fall through to their native signals (git commits, chat history,
+ * API queries, native JSONL). This prevents the lifecycle manager's
+ * `recordActivity` writes (which refresh `mtime` every poll cycle) from
+ * shadowing those richer detection methods and breaking stuck-detection.
+ */
+export declare function checkActivityLogState(activityResult: {
+    entry: ActivityLogEntry;
+    modifiedAt: Date;
+} | null): ActivityDetection | null;
+/**
+ * Derive an activity state from the JSONL entry with age-based decay.
+ *
+ * Unlike `checkActivityLogState` (which only returns actionable states),
+ * this returns any state — but reclassifies `active`/`ready` entries as
+ * `ready`/`idle` if they've aged past the active window / threshold.
+ * Use this as a last-resort fallback when native signals are unavailable.
+ */
+export declare function getActivityFallbackState(activityResult: {
+    entry: ActivityLogEntry;
+    modifiedAt: Date;
+} | null, activeWindowMs: number, thresholdMs: number): ActivityDetection | null;
+/**
+ * Build the arguments for `appendActivityEntry` from terminal output.
+ *
+ * Classifies terminal output via the provided `detectActivity` function and
+ * returns the state + trigger. Plugins call `appendActivityEntry` themselves
+ * (keeping it mockable in tests).
+ */
+export declare function classifyTerminalActivity(terminalOutput: string, detectActivity: (output: string) => ActivityState): {
+    state: ActivityState;
+    trigger: string | undefined;
+};
+/**
+ * Shared `recordActivity` implementation for all agents.
+ *
+ * Classifies terminal output, deduplicates writes (skips when the state
+ * hasn't changed and the last entry is recent), and appends to the JSONL.
+ * Actionable states (waiting_input/blocked) always write immediately.
+ */
+export declare function recordTerminalActivity(workspacePath: string, terminalOutput: string, detectActivity: (output: string) => ActivityState): Promise<void>;
+//# sourceMappingURL=activity-log.d.ts.map

package/dist/activity-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.d.ts","sourceRoot":"","sources":["../src/activity-log.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,2BAA2B,QAAgB,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CA+D/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,GACnE,iBAAiB,GAAG,IAAI,CAa1B;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,EACpE,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAClB,iBAAiB,GAAG,IAAI,CAyB1B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAChD;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAOvD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,aAAa,GAChD,OAAO,CAAC,IAAI,CAAC,CAcf"}