@creativeintelligence/abbie 0.1.0

package/src/cli/commands/report/blocked.ts

@@ -0,0 +1,165 @@
+import { Args, Flags } from "@oclif/core";
+import { detectProject, telemetry } from "../../../lib/analytics.js";
+import {
+  type AgentIdentity,
+  type BlockerType,
+  type ReportResult,
+  reportBlocked,
+} from "../../../lib/report.js";
+import { getDefaultSlackWorkspace } from "../../../lib/slack-workspace.js";
+import { AGENTS } from "../../../lib/types.js";
+import { BaseCommand } from "../../base-command.js";
+
+const DEFAULT_SLACK_WORKSPACE = getDefaultSlackWorkspace();
+
+export default class ReportBlockedCommand extends BaseCommand {
+  static override summary = "Report a blocker";
+  static override description = `Reports a blocker with escalation to DM by default.
+
+Inherits trace ID from AGENTS_TRACE_ID environment variable, or uses --trace-id flag.
+If neither is set, generates a new trace ID (with warning).
+
+DM is enabled by default for blocked (human attention needed). Use --no-dm to suppress.
+
+Error handling:
+- convex reports: CRITICAL (fails hard if persistence fails)
+- slack: WARN (continues if slack fails)
+- messages: WARN (continues if DM fails)`;
+
+  static override examples = [
+    '$ abbie report blocked "need API key for external service"',
+    '$ abbie report blocked "tests failing unexpectedly" --blocker-type error',
+    '$ abbie report blocked "waiting on upstream PR" --blocker-type dependency',
+    '$ abbie report blocked "DB locked" --blocker-type resource --no-dm',
+    '$ echo "test failures: auth module timing out" | abbie report blocked --stdin',
+    "$ verify --json --failures-only | abbie report blocked --stdin --blocker-type error",
+  ];
+
+  static override args = {
+    message: Args.string({
+      description: "Blocker description (can also be provided via stdin)",
+      required: false,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    agent: Flags.string({
+      char: "a",
+      description: "Agent identity (auto-detected if not provided)",
+      options: [...AGENTS, "custom"],
+    }),
+    "trace-id": Flags.string({
+      char: "t",
+      description: "Trace ID (inherits from AGENTS_TRACE_ID if not provided)",
+    }),
+    workspace: Flags.string({
+      char: "w",
+      description: "Slack workspace",
+      default: DEFAULT_SLACK_WORKSPACE,
+    }),
+    channel: Flags.string({
+      char: "c",
+      description: "Slack channel",
+      default: "agents",
+    }),
+    "blocker-type": Flags.string({
+      char: "b",
+      description: "Type of blocker",
+      options: ["hil", "error", "dependency", "resource"],
+      default: "hil",
+    }),
+    confidence: Flags.integer({
+      description: "Confidence score (1-10)",
+      min: 1,
+      max: 10,
+    }),
+    "no-dm": Flags.boolean({
+      description: "Suppress DM (blocked DMs by default)",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Preview without executing",
+      default: false,
+    }),
+    stdin: Flags.boolean({
+      description: "Read message from stdin",
+      default: false,
+    }),
+  };
+
+  async execute(): Promise<ReportResult> {
+    const { args, flags } = await this.parse(ReportBlockedCommand);
+    this.parsedFlags = flags;
+
+    // Resolve message from args or stdin
+    let message = args.message;
+    if (flags.stdin || !message) {
+      const stdinContent = await this.readStdin();
+      if (stdinContent) {
+        message = stdinContent;
+      }
+    }
+
+    // Validate that we have a message
+    if (!message) {
+      this.error("Message required: provide as argument or via --stdin", { exit: 2 });
+    }
+
+    // Warn if no trace ID is set
+    if (!flags["trace-id"] && !process.env.AGENTS_TRACE_ID) {
+      this.warn("No trace ID set - generating new one. Consider using AGENTS_TRACE_ID env var.");
+    }
+
+    const result = await reportBlocked(message, {
+      agent: flags.agent as AgentIdentity | undefined,
+      traceId: flags["trace-id"],
+      workspace: flags.workspace,
+      channel: flags.channel,
+      confidence: flags.confidence,
+      blockerType: flags["blocker-type"] as BlockerType,
+      noDm: flags["no-dm"],
+      dryRun: flags["dry-run"],
+    });
+
+    // Track blocker in PostHog
+    telemetry.setProperties({ trace_id: result.traceId });
+    telemetry.trackSession("blocked", {
+      agent: result.agent,
+      blocker_type: flags["blocker-type"],
+      confidence: flags.confidence,
+      project: detectProject(),
+    });
+
+    if (!this.jsonEnabled?.()) {
+      this.renderTextOutput(result);
+    }
+
+    // Exit with error if report persistence failed (critical)
+    if (!result.convex.success) {
+      this.error(`convex record failed: ${result.convex.error}`, { exit: 1 });
+    }
+
+    return result;
+  }
+
+  private renderTextOutput(result: ReportResult): void {
+    if (result.success) {
+      this.log(`blocked reported: ${result.traceId}`);
+      this.log(`agent: ${result.agent}`);
+      if (!result.messages) {
+        this.logInfo("DM suppressed via --no-dm");
+      }
+    } else {
+      this.log(`failed: ${result.convex.error || result.slack.error}`);
+    }
+
+    // Show warnings for non-critical failures
+    if (!result.slack.success) {
+      this.warn(`slack: ${result.slack.error}`);
+    }
+    if (result.messages && !result.messages.success) {
+      this.warn(`messages: ${result.messages.error}`);
+    }
+  }
+}

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

@@ -0,0 +1,179 @@
+import { Args, Flags } from "@oclif/core";
+import { detectProject, telemetry } from "../../../lib/analytics.js";
+import { type AgentIdentity, type ReportResult, reportComplete } from "../../../lib/report.js";
+import { getDefaultSlackWorkspace } from "../../../lib/slack-workspace.js";
+import { AGENTS } from "../../../lib/types.js";
+import { BaseCommand } from "../../base-command.js";
+
+const DEFAULT_SLACK_WORKSPACE = getDefaultSlackWorkspace();
+
+export default class ReportCompleteCommand extends BaseCommand {
+  static override summary = "Report task completion";
+  static override description = `Finalizes a trace with completion status.
+
+Inherits trace ID from AGENTS_TRACE_ID environment variable, or uses --trace-id flag.
+If neither is set, generates a new trace ID (with warning).
+
+Error handling:
+- convex reports: CRITICAL (fails hard if persistence fails)
+- slack: WARN (continues if slack fails)
+- messages: WARN (continues if DM fails)`;
+
+  static override examples = [
+    '$ abbie report complete "feature implemented"',
+    '$ abbie report complete "ARBOR-123 done" --confidence 9',
+    '$ abbie report complete "tests passing" --dm',
+    '$ abbie report complete "shipped" --artifacts "src/feature.ts,src/feature.test.ts"',
+    '$ echo "all tests passing, feature ready" | abbie report complete --stdin',
+    "$ verify --format=summary | abbie report complete --stdin --confidence 9",
+  ];
+
+  static override args = {
+    message: Args.string({
+      description: "Completion summary (can also be provided via stdin)",
+      required: false,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    agent: Flags.string({
+      char: "a",
+      description: "Agent identity (auto-detected if not provided)",
+      options: [...AGENTS, "custom"],
+    }),
+    "trace-id": Flags.string({
+      char: "t",
+      description: "Trace ID (inherits from AGENTS_TRACE_ID if not provided)",
+    }),
+    workspace: Flags.string({
+      char: "w",
+      description: "Slack workspace",
+      default: DEFAULT_SLACK_WORKSPACE,
+    }),
+    channel: Flags.string({
+      char: "c",
+      description: "Slack channel",
+      default: "agents",
+    }),
+    confidence: Flags.integer({
+      description: "Confidence score (1-10)",
+      min: 1,
+      max: 10,
+    }),
+    dm: Flags.boolean({
+      description: "Also send DM to luke",
+      default: false,
+    }),
+    "no-dm": Flags.boolean({
+      description: "Suppress DM (overrides --dm)",
+      default: false,
+    }),
+    artifacts: Flags.string({
+      description: "Comma-separated list of artifact paths",
+    }),
+    "dry-run": Flags.boolean({
+      description: "Preview without executing",
+      default: false,
+    }),
+    stdin: Flags.boolean({
+      description: "Read message from stdin",
+      default: false,
+    }),
+    gist: Flags.boolean({
+      char: "g",
+      description: "Create GitHub gist from completion event (for orchestration handoffs)",
+      default: false,
+    }),
+    "gist-description": Flags.string({
+      description: "Gist description (defaults to message)",
+      dependsOn: ["gist"],
+    }),
+    "gist-public": Flags.boolean({
+      description: "Make gist public (default: secret)",
+      default: false,
+      dependsOn: ["gist"],
+    }),
+  };
+
+  async execute(): Promise<ReportResult> {
+    const { args, flags } = await this.parse(ReportCompleteCommand);
+    this.parsedFlags = flags;
+
+    // Resolve message from args or stdin
+    let message = args.message;
+    if (flags.stdin || !message) {
+      const stdinContent = await this.readStdin();
+      if (stdinContent) {
+        message = stdinContent;
+      }
+    }
+
+    // Validate that we have a message
+    if (!message) {
+      this.error("Message required: provide as argument or via --stdin", { exit: 2 });
+    }
+
+    // Warn if no trace ID is set
+    if (!flags["trace-id"] && !process.env.AGENTS_TRACE_ID) {
+      this.warn("No trace ID set - generating new one. Consider using AGENTS_TRACE_ID env var.");
+    }
+
+    const artifacts = flags.artifacts?.split(",").map((s) => s.trim());
+
+    const result = await reportComplete(message, {
+      agent: flags.agent as AgentIdentity | undefined,
+      traceId: flags["trace-id"],
+      workspace: flags.workspace,
+      channel: flags.channel,
+      confidence: flags.confidence,
+      dm: flags.dm,
+      noDm: flags["no-dm"],
+      artifacts,
+      dryRun: flags["dry-run"],
+      gist: flags.gist,
+      gistDescription: flags["gist-description"],
+      gistPublic: flags["gist-public"],
+    });
+
+    // Track session completion in PostHog
+    telemetry.setProperties({ trace_id: result.traceId });
+    telemetry.trackSession("completed", {
+      agent: result.agent,
+      confidence: flags.confidence,
+      project: detectProject(),
+      duration_ms: result.durationMs,
+    });
+
+    if (!this.jsonEnabled?.()) {
+      this.renderTextOutput(result);
+    }
+
+    // Exit with error if report persistence failed (critical)
+    if (!result.convex.success) {
+      this.error(`convex record failed: ${result.convex.error}`, { exit: 1 });
+    }
+
+    return result;
+  }
+
+  private renderTextOutput(result: ReportResult): void {
+    if (result.success) {
+      this.log(`completed: ${result.traceId}`);
+      this.log(`agent: ${result.agent}`);
+      if (result.gistUrl) {
+        this.log(`gist: ${result.gistUrl}`);
+      }
+    } else {
+      this.log(`failed: ${result.convex.error || result.slack.error}`);
+    }
+
+    // Show warnings for non-critical failures
+    if (!result.slack.success) {
+      this.warn(`slack: ${result.slack.error}`);
+    }
+    if (result.messages && !result.messages.success) {
+      this.warn(`messages: ${result.messages.error}`);
+    }
+  }
+}

package/src/cli/commands/report/progress.ts

@@ -0,0 +1,142 @@
+import { Args, Flags } from "@oclif/core";
+import { type AgentIdentity, type ReportResult, reportProgress } from "../../../lib/report.js";
+import { getDefaultSlackWorkspace } from "../../../lib/slack-workspace.js";
+import { AGENTS } from "../../../lib/types.js";
+import { BaseCommand } from "../../base-command.js";
+
+const DEFAULT_SLACK_WORKSPACE = getDefaultSlackWorkspace();
+
+export default class ReportProgressCommand extends BaseCommand {
+  static override summary = "Report progress on current task";
+  static override description = `Updates progress on an existing trace.
+
+Inherits trace ID from AGENTS_TRACE_ID environment variable, or uses --trace-id flag.
+If neither is set, generates a new trace ID (with warning).
+
+Error handling:
+- convex reports: CRITICAL (fails hard if persistence fails)
+- slack: WARN (continues if slack fails)
+- messages: WARN (continues if DM fails)`;
+
+  static override examples = [
+    '$ abbie report progress "phase 2/3 complete"',
+    '$ abbie report progress "implementing tests" --confidence 7',
+    '$ abbie report progress "50% done" --trace-id tr_abc123',
+    '$ AGENTS_TRACE_ID=tr_abc123 abbie report progress "checkpoint"',
+    '$ echo "tests passing, moving to implementation" | abbie report progress --stdin',
+    "$ verify --format=summary | abbie report progress --stdin --confidence 8",
+  ];
+
+  static override args = {
+    message: Args.string({
+      description: "Progress update message (can also be provided via stdin)",
+      required: false,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    agent: Flags.string({
+      char: "a",
+      description: "Agent identity (auto-detected if not provided)",
+      options: [...AGENTS, "custom"],
+    }),
+    "trace-id": Flags.string({
+      char: "t",
+      description: "Trace ID (inherits from AGENTS_TRACE_ID if not provided)",
+    }),
+    workspace: Flags.string({
+      char: "w",
+      description: "Slack workspace",
+      default: DEFAULT_SLACK_WORKSPACE,
+    }),
+    channel: Flags.string({
+      char: "c",
+      description: "Slack channel",
+      default: "agents",
+    }),
+    confidence: Flags.integer({
+      description: "Confidence score (1-10)",
+      min: 1,
+      max: 10,
+    }),
+    dm: Flags.boolean({
+      description: "Also send DM to luke",
+      default: false,
+    }),
+    "no-dm": Flags.boolean({
+      description: "Suppress DM (overrides --dm)",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Preview without executing",
+      default: false,
+    }),
+    stdin: Flags.boolean({
+      description: "Read message from stdin",
+      default: false,
+    }),
+  };
+
+  async execute(): Promise<ReportResult> {
+    const { args, flags } = await this.parse(ReportProgressCommand);
+    this.parsedFlags = flags;
+
+    // Resolve message from args or stdin
+    let message = args.message;
+    if (flags.stdin || !message) {
+      const stdinContent = await this.readStdin();
+      if (stdinContent) {
+        message = stdinContent;
+      }
+    }
+
+    // Validate that we have a message
+    if (!message) {
+      this.error("Message required: provide as argument or via --stdin", { exit: 2 });
+    }
+
+    // Warn if no trace ID is set
+    if (!flags["trace-id"] && !process.env.AGENTS_TRACE_ID) {
+      this.warn("No trace ID set - generating new one. Consider using AGENTS_TRACE_ID env var.");
+    }
+
+    const result = await reportProgress(message, {
+      agent: flags.agent as AgentIdentity | undefined,
+      traceId: flags["trace-id"],
+      workspace: flags.workspace,
+      channel: flags.channel,
+      confidence: flags.confidence,
+      dm: flags.dm,
+      noDm: flags["no-dm"],
+      dryRun: flags["dry-run"],
+    });
+
+    if (!this.jsonEnabled?.()) {
+      this.renderTextOutput(result);
+    }
+
+    // Exit with error if report persistence failed (critical)
+    if (!result.convex.success) {
+      this.error(`convex record failed: ${result.convex.error}`, { exit: 1 });
+    }
+
+    return result;
+  }
+
+  private renderTextOutput(result: ReportResult): void {
+    if (result.success) {
+      this.log(`progress recorded: ${result.traceId}`);
+    } else {
+      this.log(`failed: ${result.convex.error || result.slack.error}`);
+    }
+
+    // Show warnings for non-critical failures
+    if (!result.slack.success) {
+      this.warn(`slack: ${result.slack.error}`);
+    }
+    if (result.messages && !result.messages.success) {
+      this.warn(`messages: ${result.messages.error}`);
+    }
+  }
+}

package/src/cli/commands/report/start.ts

@@ -0,0 +1,140 @@
+import { Args, Flags } from "@oclif/core";
+import { detectProject, hashForTelemetry, telemetry } from "../../../lib/analytics.js";
+import { type AgentIdentity, type ReportResult, reportStart } from "../../../lib/report.js";
+import { getDefaultSlackWorkspace } from "../../../lib/slack-workspace.js";
+import { AGENTS } from "../../../lib/types.js";
+import { BaseCommand } from "../../base-command.js";
+
+const DEFAULT_SLACK_WORKSPACE = getDefaultSlackWorkspace();
+
+export default class ReportStartCommand extends BaseCommand {
+  static override summary = "Report start of a new task/trace";
+  static override description = `Begins a new trace and persists to Convex reports + Slack.
+
+Always generates a new trace ID. Exports AGENTS_TRACE_ID for subsequent commands.
+
+Error handling:
+- convex reports: CRITICAL (fails hard if persistence fails)
+- slack: WARN (continues if slack fails)
+- messages: WARN (continues if DM fails)`;
+
+  static override examples = [
+    '$ abbie report start "beginning loop on arbor"',
+    '$ abbie report start "implementing ARBOR-123" --confidence 8',
+    '$ abbie report start "overnight work" --dm',
+    '$ abbie report start "test run" --dry-run',
+    '$ export AGENTS_TRACE_ID=$(abbie report start "task" --json -q | jq -r .traceId)',
+    '$ echo "starting feature work" | abbie report start --stdin',
+    "$ verify --json | jq -r .summary | abbie report start --stdin",
+  ];
+
+  static override args = {
+    message: Args.string({
+      description: "Task description (can also be provided via stdin)",
+      required: false,
+    }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    agent: Flags.string({
+      char: "a",
+      description: "Agent identity (auto-detected if not provided)",
+      options: [...AGENTS, "custom"],
+    }),
+    workspace: Flags.string({
+      char: "w",
+      description: "Slack workspace",
+      default: DEFAULT_SLACK_WORKSPACE,
+    }),
+    channel: Flags.string({
+      char: "c",
+      description: "Slack channel",
+      default: "agents",
+    }),
+    confidence: Flags.integer({
+      description: "Confidence score (1-10)",
+      min: 1,
+      max: 10,
+    }),
+    dm: Flags.boolean({
+      description: "Also send DM to luke",
+      default: false,
+    }),
+    "dry-run": Flags.boolean({
+      description: "Preview without executing",
+      default: false,
+    }),
+    stdin: Flags.boolean({
+      description: "Read message from stdin",
+      default: false,
+    }),
+  };
+
+  async execute(): Promise<ReportResult> {
+    const { args, flags } = await this.parse(ReportStartCommand);
+    this.parsedFlags = flags;
+
+    // Resolve message from args or stdin
+    let message = args.message;
+    if (flags.stdin || !message) {
+      const stdinContent = await this.readStdin();
+      if (stdinContent) {
+        message = stdinContent;
+      }
+    }
+
+    // Validate that we have a message
+    if (!message) {
+      this.error("Message required: provide as argument or via --stdin", { exit: 2 });
+    }
+
+    const result = await reportStart(message, {
+      agent: flags.agent as AgentIdentity | undefined,
+      workspace: flags.workspace,
+      channel: flags.channel,
+      confidence: flags.confidence,
+      dm: flags.dm,
+      dryRun: flags["dry-run"],
+    });
+
+    // Ensure emitted events correlate to the newly-created trace.
+    telemetry.setProperties({ trace_id: result.traceId });
+    telemetry.trackSession("started", {
+      agent: result.agent,
+      confidence: flags.confidence,
+      project: detectProject(),
+      goal_hash: hashForTelemetry(message),
+    });
+
+    if (!this.jsonEnabled?.()) {
+      this.renderTextOutput(result);
+    }
+
+    // Exit with error if report persistence failed (critical)
+    if (!result.convex.success) {
+      this.error(`convex record failed: ${result.convex.error}`, { exit: 1 });
+    }
+
+    return result;
+  }
+
+  private renderTextOutput(result: ReportResult): void {
+    if (result.success) {
+      this.log(`started trace: ${result.traceId}`);
+      this.log(`agent: ${result.agent}`);
+      this.logInfo("export AGENTS_TRACE_ID for subsequent commands:");
+      this.log(`export AGENTS_TRACE_ID="${result.traceId}"`);
+    } else {
+      this.log(`failed: ${result.convex.error || result.slack.error}`);
+    }
+
+    // Show warnings for non-critical failures
+    if (!result.slack.success) {
+      this.warn(`slack: ${result.slack.error}`);
+    }
+    if (result.messages && !result.messages.success) {
+      this.warn(`messages: ${result.messages.error}`);
+    }
+  }
+}