@creativeintelligence/abbie 0.1.0

package/src/cli/commands/session/await.ts

@@ -0,0 +1,83 @@
+import { Args, Flags } from "@oclif/core";
+import { getActiveSessionManager } from "../../../lib/active-sessions.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class SessionAwait extends BaseCommand {
+  static override description = "Wait for a session to complete and return output";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> session await hostagent-20241225-120000-abc1",
+    "<%= config.bin %> session await hostagent-20241225-120000-abc1 --timeout 120",
+    "<%= config.bin %> session await hostagent-20241225-120000-abc1 --poll-interval 1 --json",
+  ];
+
+  static override args = {
+    session_id: Args.string({
+      description: "Session ID to wait for",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    timeout: Flags.integer({
+      description: "Maximum wait time in seconds",
+      default: 300,
+    }),
+    "poll-interval": Flags.integer({
+      description: "Seconds between status checks",
+      default: 2,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(SessionAwait);
+    this.parsedFlags = flags;
+
+    const manager = getActiveSessionManager();
+    const session = await manager.getAsync(args.session_id);
+
+    if (!session) {
+      this.error(`Session not found: ${args.session_id}`);
+    }
+
+    const timeoutMs = flags.timeout * 1000;
+    const pollIntervalMs = flags["poll-interval"] * 1000;
+    const isJson = flags.json || flags.format === "json";
+
+    if (!isJson) {
+      this.logInfo(
+        `Waiting for session ${args.session_id} (timeout ${flags.timeout}s, poll ${flags["poll-interval"]}s)...`,
+      );
+    }
+
+    const result = await manager.await(args.session_id, {
+      pollIntervalMs,
+      timeoutMs,
+    });
+
+    if (isJson) {
+      return { session_id: args.session_id, ...result };
+    }
+
+    if (result.status === "timeout") {
+      this.logInfo(`Timeout waiting for session ${args.session_id}`);
+      return { session_id: args.session_id, ...result };
+    }
+
+    if (result.status === "stopped") {
+      this.logInfo(`Session ${args.session_id} was stopped`);
+    } else if (result.error && result.status === "failed") {
+      this.logInfo(result.error);
+    }
+
+    if (typeof result.output === "string") {
+      this.log(result.output);
+    } else if (result.output !== undefined) {
+      this.log(JSON.stringify(result.output, null, 2));
+    }
+
+    return { session_id: args.session_id, ...result };
+  }
+}

package/src/cli/commands/session/complete.ts

@@ -0,0 +1,100 @@
+import { Args, Flags } from "@oclif/core";
+import { createEvent, EventStore } from "../../../lib/events.js";
+import { HeartbeatManager } from "../../../lib/heartbeat.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class SessionComplete extends BaseCommand {
+  static override description = "Mark a session as complete";
+  static override hidden = false;
+
+  static override examples = [
+    '<%= config.bin %> session complete SESSION_ID --summary "implemented auth flow"',
+    '<%= config.bin %> session complete SESSION_ID --summary "fixed bug" --status success',
+    '<%= config.bin %> session complete SESSION_ID --summary "blocked on API" --status blocked',
+  ];
+
+  static override args = {
+    session_id: Args.string({
+      description: "Session ID to complete",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    summary: Flags.string({
+      char: "s",
+      description: "Summary of work completed",
+      required: true,
+    }),
+    status: Flags.string({
+      description: "Completion status",
+      options: ["success", "partial", "blocked", "failed"],
+      default: "success",
+    }),
+    artifacts: Flags.string({
+      char: "a",
+      description: "Comma-separated list of artifact paths",
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(SessionComplete);
+    this.parsedFlags = flags;
+
+    const heartbeat = new HeartbeatManager();
+    const events = new EventStore();
+
+    const session = heartbeat.get(args.session_id);
+    if (!session) {
+      this.error(`Session not found: ${args.session_id}`);
+    }
+
+    // Remove from active sessions
+    heartbeat.deregister(args.session_id);
+
+    // Parse artifacts - convert paths to artifact objects
+    const artifactPaths = flags.artifacts ? flags.artifacts.split(",").map((a) => a.trim()) : [];
+    const artifacts = artifactPaths.map((ref) => ({
+      type: "file" as const,
+      ref,
+    }));
+
+    // Calculate duration
+    const durationMs = Date.now() - new Date(session.started_at).getTime();
+
+    // Emit completion event (or blocked if status indicates blocking)
+    if (flags.status === "blocked") {
+      events.append(
+        createEvent.blocked(args.session_id, session.agent, {
+          reason: flags.summary,
+          blocker_type: "hil",
+        }),
+      );
+    } else {
+      events.append(
+        createEvent.complete(args.session_id, session.agent, {
+          summary: flags.summary,
+          artifacts,
+          duration_ms: durationMs,
+        }),
+      );
+    }
+
+    const result = {
+      session_id: args.session_id,
+      status: flags.status,
+      summary: flags.summary,
+      artifacts: artifactPaths,
+      duration_ms: durationMs,
+    };
+
+    if (flags.json || flags.format === "json") {
+      return result;
+    }
+
+    this.logInfo(`Session ${args.session_id} completed (${flags.status})`);
+    this.log(`Summary: ${flags.summary}`);
+    return result;
+  }
+}

package/src/cli/commands/session/create.ts

@@ -0,0 +1,92 @@
+import { Flags } from "@oclif/core";
+import { createEvent, EventStore } from "../../../lib/events.js";
+import { HeartbeatManager } from "../../../lib/heartbeat.js";
+import { AGENTS } from "../../../lib/types.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class SessionCreate extends BaseCommand {
+  static override description = "Create and register a new agent session";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> session create --project hostagent --agent claude",
+    "<%= config.bin %> session create --project hostagent --agent codex --issue ZO-123",
+    "<%= config.bin %> session create --json",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    project: Flags.string({
+      char: "p",
+      description: "Project name",
+      required: true,
+    }),
+    agent: Flags.string({
+      char: "a",
+      description: "Agent type (claude, codex, copilot, gemini)",
+      required: true,
+      options: [...AGENTS],
+    }),
+    issue: Flags.string({
+      char: "i",
+      description: "Linear issue reference (e.g., ZO-123)",
+    }),
+    worktree: Flags.string({
+      char: "w",
+      description: "Git worktree path",
+    }),
+    task: Flags.string({
+      char: "t",
+      description: "Initial task description",
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { flags } = await this.parse(SessionCreate);
+    this.parsedFlags = flags;
+
+    const heartbeat = new HeartbeatManager();
+    const events = new EventStore();
+
+    // Generate session ID with project prefix for easier lookup
+    const sessionId = this.generateSessionId(flags.project);
+
+    // Register with heartbeat manager
+    const session = heartbeat.register(
+      sessionId,
+      flags.agent as "claude" | "codex" | "copilot" | "gemini",
+      {
+        project: flags.project,
+        issue: flags.issue,
+        worktree: flags.worktree,
+      },
+    );
+
+    // Set initial task if provided
+    if (flags.task) {
+      heartbeat.heartbeat(sessionId, { current_task: flags.task });
+    }
+
+    // Emit session:start event
+    events.append(
+      createEvent.sessionStart(sessionId, flags.agent, {
+        project: flags.project,
+        issue: flags.issue,
+        worktree: flags.worktree,
+      }),
+    );
+
+    if (flags.json || flags.format === "json") {
+      return session;
+    }
+
+    this.log(sessionId);
+    return { session_id: sessionId };
+  }
+
+  private generateSessionId(project: string): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 7);
+    return `${project}-${timestamp}-${random}`;
+  }
+}

package/src/cli/commands/session/heartbeat.ts

@@ -0,0 +1,63 @@
+import { Args, Flags } from "@oclif/core";
+import { createEvent, EventStore } from "../../../lib/events.js";
+import { HeartbeatManager } from "../../../lib/heartbeat.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class SessionHeartbeat extends BaseCommand {
+  static override description = "Send heartbeat for an active session";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> session heartbeat SESSION_ID",
+    '<%= config.bin %> session heartbeat SESSION_ID --task "implementing auth"',
+    "<%= config.bin %> session heartbeat SESSION_ID --json",
+  ];
+
+  static override args = {
+    session_id: Args.string({
+      description: "Session ID to heartbeat",
+      required: true,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    task: Flags.string({
+      char: "t",
+      description: "Current task description",
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { args, flags } = await this.parse(SessionHeartbeat);
+    this.parsedFlags = flags;
+
+    const heartbeat = new HeartbeatManager();
+    const events = new EventStore();
+
+    const session = heartbeat.heartbeat(args.session_id, {
+      current_task: flags.task,
+    });
+
+    if (!session) {
+      this.error(`Session not found: ${args.session_id}`);
+    }
+
+    // Emit heartbeat event - only emit active/idle status
+    const eventStatus =
+      session.status === "active" || session.status === "idle" ? session.status : "active";
+    events.append(
+      createEvent.heartbeat(args.session_id, session.agent, {
+        current_task: flags.task,
+        status: eventStatus,
+      }),
+    );
+
+    if (flags.json || flags.format === "json") {
+      return session;
+    }
+
+    this.logInfo(`Heartbeat sent for ${args.session_id} (status: ${session.status})`);
+    return session;
+  }
+}

package/src/cli/commands/session/list.ts

@@ -0,0 +1,281 @@
+import { spawnSync } from "node:child_process";
+import { getHttpClient, api, type Session } from "@abbie/sdk/convex";
+import { Flags } from "@oclif/core";
+import { type ActiveSession, getActiveSessionManager } from "../../../lib/active-sessions.js";
+import { getDeviceId } from "../../../lib/device.js";
+import { BaseCommand } from "../../base-command.js";
+
+export default class SessionList extends BaseCommand {
+  static override description = "List agent sessions (spawned via session start)";
+  static override hidden = false;
+
+  static override examples = [
+    "<%= config.bin %> session list",
+    "<%= config.bin %> session list --running",
+    "<%= config.bin %> session list --active",
+    "<%= config.bin %> session list --project hostagent",
+    "<%= config.bin %> session list --all",
+    "<%= config.bin %> session list --json",
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    project: Flags.string({
+      char: "p",
+      description: "Filter by project",
+    }),
+    running: Flags.boolean({
+      char: "r",
+      description: "Show only running sessions",
+      default: false,
+    }),
+    active: Flags.boolean({
+      description: "Alias for --running (compat with older docs/skills)",
+      default: false,
+    }),
+    completed: Flags.boolean({
+      description: "Show only completed sessions",
+      default: false,
+    }),
+    failed: Flags.boolean({
+      description: "Show only failed sessions",
+      default: false,
+    }),
+    all: Flags.boolean({
+      char: "a",
+      description: "Show all sessions (default shows recent 20)",
+      default: false,
+    }),
+    limit: Flags.integer({
+      char: "n",
+      description: "Maximum sessions to show",
+      default: 20,
+    }),
+  };
+
+  protected async execute(): Promise<unknown> {
+    const { flags } = await this.parse(SessionList);
+    this.parsedFlags = flags;
+
+    // Determine status filter
+    let statusFilter: ActiveSession["status"] | undefined;
+    if (flags.running || flags.active) statusFilter = "running";
+    else if (flags.completed) statusFilter = "completed";
+    else if (flags.failed) statusFilter = "failed";
+
+    let sessions: ActiveSession[] = [];
+
+    const deviceId = getDeviceId();
+    const queryLimit = flags.all ? 500 : Math.max(flags.limit, 50);
+
+    const client = getHttpClient();
+
+    let storeSessions: Session[] = [];
+
+    try {
+      const rawSessions = await client.query(api.sessions.list, { deviceId, limit: queryLimit });
+      storeSessions = rawSessions as unknown as Session[];
+    } catch (error) {
+      this.logWarn(`Store read failed: ${(error as Error).message}`);
+    }
+
+    const toActiveSession = (s: (typeof storeSessions)[number]): ActiveSession => {
+      const status =
+        s.status === "spawned" ? "running" : (s.status as unknown as ActiveSession["status"]);
+
+      return {
+        session_id: s.sessionId,
+        agent: s.agent as ActiveSession["agent"],
+        project: s.project,
+        goal: s.goal ?? "",
+        issue: s.issue ?? undefined,
+        cwd: s.cwd,
+        pid: s.pid ?? 0,
+        started_at: new Date(s.startedAt).toISOString(),
+        status,
+        prompt_path: s.promptPath ?? undefined,
+        output_path: s.outputPath ?? undefined,
+        trace_id: s.traceId ?? undefined,
+        parent_session_id: s.parentSessionId ?? undefined,
+        read_only: (s.metadata as { readOnly?: boolean } | undefined)?.readOnly ?? undefined,
+      };
+    };
+
+    const applyFilters = (s: ActiveSession): boolean => {
+      if (flags.project && s.project !== flags.project) return false;
+      if (statusFilter && s.status !== statusFilter) return false;
+      return true;
+    };
+
+    sessions = storeSessions
+      .map(toActiveSession)
+      .filter(applyFilters)
+      .sort((a, b) => new Date(b.started_at).getTime() - new Date(a.started_at).getTime());
+
+    // Detect and mark stale "running" sessions whose process/pane is dead.
+    // Cross-reference local active-sessions JSON which mark-done updates.
+    const manager = getActiveSessionManager();
+    for (const session of sessions) {
+      if (session.status !== "running") continue;
+
+      // Check if local JSON already has a terminal status (mark-done ran but store wasn't updated)
+      const localSession = manager.get(session.session_id);
+      if (localSession && localSession.status !== "running") {
+        session.status = localSession.status;
+        session.exit_code = localSession.exit_code;
+        try {
+          await client.mutation(api.sessions.update, {
+            sessionId: session.session_id,
+            status: localSession.status === "stopped" ? "stopped" : localSession.status,
+            endedAt: Date.now(),
+          });
+        } catch {}
+        continue;
+      }
+
+      // Process/pane liveness check
+      let dead = false;
+
+      if (session.pid > 0) {
+        try {
+          process.kill(session.pid, 0);
+        } catch {
+          dead = true;
+        }
+      } else if (localSession?.pane_id && localSession.spawn_mode === "terminal") {
+        const result = spawnSync("tmux", ["list-panes", "-t", localSession.pane_id], {
+          stdio: ["ignore", "ignore", "ignore"],
+        });
+        if (result.status !== 0) {
+          dead = true;
+        }
+      } else if (localSession && localSession.pid <= 0 && !localSession.pane_id) {
+        // No PID and no pane — cannot verify liveness
+        dead = true;
+      }
+
+      if (dead) {
+        session.status = "failed";
+        try {
+          await client.mutation(api.sessions.update, {
+            sessionId: session.session_id,
+            status: "failed",
+            endedAt: Date.now(),
+          });
+        } catch {}
+        if (localSession && localSession.status === "running") {
+          localSession.status = "failed";
+          const { writeFileSync } = await import("node:fs");
+          const { join } = await import("node:path");
+          const { homedir } = await import("node:os");
+          const sessionPath = join(
+            homedir(),
+            ".abbie",
+            "active-sessions",
+            `${session.session_id}.json`,
+          );
+          writeFileSync(sessionPath, JSON.stringify(localSession, null, 2));
+        }
+      }
+    }
+
+    // Apply limit unless --all
+    if (!flags.all && sessions.length > flags.limit) {
+      sessions = sessions.slice(0, flags.limit);
+    }
+
+    // JSON output
+    if (flags.json || flags.format === "json") {
+      return sessions;
+    }
+
+    // NDJSON output
+    if (this.ndjsonEnabled()) {
+      this.outputNdjson(sessions);
+      return sessions;
+    }
+
+    // Text output
+    if (sessions.length === 0) {
+      this.logInfo("No sessions found");
+      return [];
+    }
+
+    const total = storeSessions.length;
+    const showing = sessions.length;
+    const limitNote =
+      !flags.all && total > showing ? ` (showing ${showing}/${total}, use --all for more)` : "";
+
+    this.logInfo(`Sessions${limitNote}:\n`);
+
+    for (const session of sessions) {
+      const statusIcon = this.getStatusIcon(session.status);
+      const duration = this.getDuration(session);
+      const age = this.getAge(session.started_at);
+
+      this.log(`${statusIcon} ${session.session_id}`);
+      this.log(`   Agent: ${session.agent}`);
+      this.log(`   Project: ${session.project}`);
+      this.log(`   Goal: ${this.truncate(session.goal, 60)}`);
+      if (session.issue) {
+        this.log(`   Issue: ${session.issue}`);
+      }
+      this.log(
+        `   Status: ${session.status}${session.exit_code !== undefined ? ` (exit ${session.exit_code})` : ""}`,
+      );
+      this.log(`   Started: ${age}${duration ? ` (${duration})` : ""}`);
+      this.log(`   PID: ${session.pid}`);
+      this.log("");
+    }
+
+    return sessions;
+  }
+
+  private getStatusIcon(status: ActiveSession["status"]): string {
+    switch (status) {
+      case "running":
+        return "🟢";
+      case "completed":
+        return "✅";
+      case "failed":
+        return "❌";
+      case "stopped":
+        return "⏹️";
+      default:
+        return "⚪";
+    }
+  }
+
+  private getAge(timestamp: string): string {
+    const ms = Date.now() - new Date(timestamp).getTime();
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    if (days > 0) {
+      return `${days}d ${hours % 24}h ago`;
+    }
+    if (hours > 0) {
+      return `${hours}h ${minutes % 60}m ago`;
+    }
+    if (minutes > 0) {
+      return `${minutes}m ago`;
+    }
+    return `${seconds}s ago`;
+  }
+
+  private getDuration(session: ActiveSession): string | null {
+    if (session.status === "running") {
+      return null;
+    }
+    // Estimate from started_at to now for completed sessions
+    // (we don't have completed_at in the interface, could add later)
+    return null;
+  }
+
+  private truncate(str: string, maxLength: number): string {
+    if (str.length <= maxLength) return str;
+    return `${str.slice(0, maxLength - 3)}...`;
+  }
+}