@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/cli.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from './cli/argv';
+import { dispatchConsole, isConsoleCommand } from './cli/commands/console';
+import { dispatchDispatch, isDispatchCommand } from './cli/commands/dispatch';
+import { dispatchHarness, isHarnessCommand } from './cli/commands/harness';
+import { dispatchHookCli, isHookCommand } from './cli/commands/hook';
+import { dispatchLedger, isLedgerCommand } from './cli/commands/ledger';
+import { dispatchLocalWorkflow, isLocalWorkflowCommand } from './cli/commands/local-workflow';
+import { dispatchMemory, isMemoryCommand } from './cli/commands/memory';
+import { dispatchRubric, isRubricCommand } from './cli/commands/rubric';
+import { dispatchRelease, isReleaseCommand } from './cli/commands/release';
+import { dispatchSeat, isSeatCommand } from './cli/commands/seat';
+import { dispatchSession, isSessionCommand } from './cli/commands/session';
+import { advancedUsage, usage } from './cli/usage';
+import { dispatchSync, isSyncCommand } from './cli/commands/sync';
+import { dispatchWorkflow, isWorkflowCommand } from './cli/commands/workflow';
+import { dispatchWorkspace, isWorkspaceCommand } from './cli/commands/workspace';
+
+/**
+ * Thin dispatcher. The former monolithic `cli.ts` was split across
+ * `cli/argv.ts` (parsing), `cli/usage.ts` (help text), and per-category
+ * command modules. This entry point only classifies the top-level command and
+ * delegates to the matching command module.
+ */
+// Clean error rendering: a CLI failure must print a human-readable message,
+// never a raw stack/bundle dump (see CONTRIBUTING.md). Set ETQ_DEBUG=1 for stacks.
+function renderCliError(err: unknown): never {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`error: ${message}`);
+  if (process.env.ETQ_DEBUG && err instanceof Error && err.stack) {
+    console.error(err.stack);
+  }
+  process.exit(1);
+}
+process.on('uncaughtException', renderCliError);
+process.on('unhandledRejection', renderCliError);
+
+const { positionals, flags } = parseArgs(process.argv.slice(2));
+const command = positionals[0];
+
+if (command === 'version' || flags.version) {
+  const { readFileSync } = await import('node:fs');
+  const pkg = JSON.parse(
+    readFileSync(new URL('../../../package.json', import.meta.url), 'utf-8'),
+  ) as { name?: string; version?: string };
+  console.log(`etiquette ${pkg.version ?? 'unknown'} (${pkg.name ?? 'etiquette'})`);
+  process.exit(0);
+}
+
+const SUPERVISION_COMMANDS_CLI: ReadonlySet<string> = new Set([
+  'session-open',
+  'session-status',
+  'turn-open',
+  'turn-close',
+  'session-command',
+  'session-project',
+  'session-rebuild',
+  'seat-validate',
+]);
+
+if (!command) {
+  console.error(usage());
+  process.exit(1);
+}
+
+if (command === 'help' || flags.help) {
+  console.error(positionals[1] === 'advanced' ? advancedUsage() : usage());
+  process.exit(0);
+}
+
+if (SUPERVISION_COMMANDS_CLI.has(command)) {
+  const { dispatchSupervision } = await import('./cli/commands/supervision');
+  await dispatchSupervision(command, positionals, flags);
+  process.exit(0);
+}
+
+if (command === 'agent-plane') {
+  console.error(
+    'agent-plane commands are not included in the local devkit; they return with the remote runner-plane work.',
+  );
+  process.exit(1);
+}
+
+if (isMemoryCommand(command)) {
+  await dispatchMemory(positionals, flags);
+  process.exit(0);
+}
+
+if (command === 'mcp') {
+  console.error(
+    'mcp commands are not included in the local devkit; use a source workspace.',
+  );
+  process.exit(1);
+}
+
+if (command === 'parity') {
+  console.error(
+    'parity commands are not included in the local devkit; use a source workspace.',
+  );
+  process.exit(1);
+}
+
+if (isConsoleCommand(command)) {
+  await dispatchConsole(positionals, flags);
+  process.exit(0);
+}
+
+if (isHookCommand(command)) {
+  await dispatchHookCli(positionals, flags);
+  process.exit(0);
+}
+
+if (isHarnessCommand(command)) {
+  await dispatchHarness(positionals, flags);
+  process.exit(0);
+}
+
+if (command === 'hosted') {
+  console.error(
+    'hosted commands are not included in the local devkit; use a hosted/control-plane source workspace.',
+  );
+  process.exit(1);
+}
+
+if (command === 'integration') {
+  console.error(
+    'integration commands are not included in the local devkit; use a source workspace.',
+  );
+  process.exit(1);
+}
+
+if (isLedgerCommand(command)) {
+  await dispatchLedger(positionals, flags);
+  process.exit(0);
+}
+
+if (command === 'linear') {
+  console.error(
+    'linear commands are not included in the local devkit; use a source workspace.',
+  );
+  process.exit(1);
+}
+
+if (isDispatchCommand(command)) {
+  await dispatchDispatch(positionals, flags);
+  process.exit(0);
+}
+
+if (isRubricCommand(command)) {
+  await dispatchRubric(positionals, flags);
+  process.exit(0);
+}
+
+if (isReleaseCommand(command)) {
+  await dispatchRelease(positionals, flags);
+  process.exit(0);
+}
+
+if (command === 'remote') {
+  console.error(
+    'remote commands are not included in the local devkit; remote execution ships with the hosted workspace product later.',
+  );
+  process.exit(1);
+}
+
+if (command === 'runtime') {
+  console.error(
+    'runtime commands are not included in the local devkit; use an infra/runtime source workspace.',
+  );
+  process.exit(1);
+}
+
+if (isSeatCommand(command)) {
+  await dispatchSeat(positionals, flags);
+  process.exit(0);
+}
+
+if (isSessionCommand(command)) {
+  await dispatchSession(positionals, flags);
+  process.exit(0);
+}
+
+if (isSyncCommand(command)) {
+  await dispatchSync(positionals, flags);
+  process.exit(0);
+}
+
+if (isWorkflowCommand(command)) {
+  await dispatchWorkflow(positionals, flags);
+  process.exit(0);
+}
+
+if (isLocalWorkflowCommand(command)) {
+  await dispatchLocalWorkflow(positionals, flags);
+  process.exit(0);
+}
+
+if (isWorkspaceCommand(command)) {
+  await dispatchWorkspace(positionals, flags);
+  process.exit(0);
+}
+
+console.error(`unknown command: ${command}`);
+console.error('');
+console.error(usage());
+process.exit(1);

package/packages/control/src/core-cli.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from './cli/argv';
+import { coreUsage } from './cli/core-usage';
+import { dispatchCoreDispatch, isCoreDispatchCommand } from './cli/commands/dispatch-core';
+import { dispatchLedger, isLedgerCommand } from './cli/commands/ledger';
+import { dispatchRubric, isRubricCommand } from './cli/commands/rubric';
+import { dispatchSeat, isSeatCommand } from './cli/commands/seat';
+import { dispatchSession, isSessionCommand } from './cli/commands/session';
+import { dispatchWorkflow, isWorkflowCommand } from './cli/commands/workflow';
+
+const { positionals, flags } = parseArgs(process.argv.slice(2));
+const command = positionals[0];
+
+if (!command || command === 'help' || flags.help) {
+  console.error(coreUsage());
+  process.exit(command || flags.help ? 0 : 1);
+}
+
+if (isSeatCommand(command)) {
+  await dispatchSeat(positionals, flags);
+  process.exit(0);
+}
+
+if (isSessionCommand(command)) {
+  await dispatchSession(positionals, flags);
+  process.exit(0);
+}
+
+if (isWorkflowCommand(command)) {
+  await dispatchWorkflow(positionals, flags);
+  process.exit(0);
+}
+
+if (isRubricCommand(command)) {
+  await dispatchRubric(positionals, flags);
+  process.exit(0);
+}
+
+if (isCoreDispatchCommand(command)) {
+  await dispatchCoreDispatch(positionals, flags);
+  process.exit(0);
+}
+
+if (isLedgerCommand(command)) {
+  await dispatchLedger(positionals, flags);
+  process.exit(0);
+}
+
+throw new Error(`etiquette-core does not include '${command}'. Use the full 'etiquette' CLI for optional runtime, hosted, adapter, console, MCP, memory, sync, or release surfaces.`);

package/packages/control/src/dispatch/decision.ts

@@ -0,0 +1,202 @@
+import type { SandboxRunReceipt } from '../rubric/types';
+import type { SeatReadinessStatus } from '../seat/readiness';
+import type { WorkflowCheckEnvelope, WorkflowCheckResult, WorkflowMode } from '../workflow/types';
+
+export const OPERATIONAL_DECISIONS = [
+  'dispatch_ready',
+  'hold_for_grant',
+  'blocked_by_capability',
+  'blocked_by_validation',
+  'quarantine_hold',
+] as const;
+
+export type OperationalDecision = typeof OPERATIONAL_DECISIONS[number];
+
+export interface OperationalDispatchDecision {
+  schema: 'operational-dispatch-decision.v0';
+  task_ref: string;
+  seat: string;
+  decision: OperationalDecision;
+  reasons: string[];
+  warnings: string[];
+  profile_hint: 'quarantine_hold' | 'batch_backlog' | 'sabbatical_improvement' | null;
+  inputs: {
+    seat_readiness: {
+      operational_status: SeatReadinessStatus['operational_status'];
+      routing_recommendation: SeatReadinessStatus['routing_recommendation'];
+      capability_trusted: boolean;
+      model_tier: SeatReadinessStatus['model_tier'];
+      effective_model_tier: SeatReadinessStatus['effective_model_tier'];
+      active_workers: number;
+      max_recommended_workers: number;
+      is_stale: boolean;
+    };
+    workflow_check: {
+      mode_id: string;
+      mode_type: WorkflowCheckResult['mode_type'];
+      recommendation: WorkflowCheckResult['recommendation'];
+      missing: string[];
+      warnings: string[];
+    };
+    strategy: {
+      requested_strategy: string | null;
+      policy: WorkflowMode['execution']['strategy_policy'];
+      supported: boolean | null;
+      unsupported: boolean | null;
+    };
+    rubric_receipt: {
+      receipt_id: string | null;
+      unexpected_outcomes: number | null;
+      accepted: boolean | null;
+    };
+  };
+  authority_boundary: {
+    can_dispatch: false;
+    can_authorize: false;
+    can_attach_grant: false;
+    can_execute: false;
+    consumer_is_engine: false;
+  };
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function isGrantOnlyBlock(workflow: WorkflowCheckResult): boolean {
+  return workflow.missing.length > 0 && workflow.missing.every((item) => item === 'grant_ref');
+}
+
+function strategyStatus(
+  status: SeatReadinessStatus,
+  requestedStrategy: string | null,
+): { supported: boolean | null; unsupported: boolean | null } {
+  if (!requestedStrategy) return { supported: null, unsupported: null };
+  return {
+    supported: status.supported_strategies.includes(requestedStrategy),
+    unsupported: status.unsupported_strategies.includes(requestedStrategy),
+  };
+}
+
+function rubricAccepted(receipt: SandboxRunReceipt | null | undefined): boolean | null {
+  if (!receipt) return null;
+  return receipt.summary.unexpected_outcomes === 0;
+}
+
+export function evaluateOperationalDispatch(options: {
+  seat: SeatReadinessStatus;
+  mode: WorkflowMode;
+  envelope: WorkflowCheckEnvelope;
+  workflow: WorkflowCheckResult;
+  sandboxReceipt?: SandboxRunReceipt | null;
+  requestedStrategy?: string | null;
+}): OperationalDispatchDecision {
+  const reasons: string[] = [];
+  const warnings: string[] = [...options.workflow.warnings];
+  let decision: OperationalDecision = 'dispatch_ready';
+  let profileHint: OperationalDispatchDecision['profile_hint'] = null;
+  const requestedStrategy = options.requestedStrategy ?? null;
+  const strategy = strategyStatus(options.seat, requestedStrategy);
+  const sandboxAccepted = rubricAccepted(options.sandboxReceipt);
+
+  if (options.envelope.advisory_consensus_claims_authority) {
+    decision = 'quarantine_hold';
+    profileHint = 'quarantine_hold';
+    reasons.push('advisory_consensus_claims_authority');
+  }
+
+  if (decision === 'dispatch_ready' && options.seat.routing_recommendation !== 'route_if_policy_allows') {
+    decision = 'blocked_by_capability';
+    reasons.push(`seat_routing_${options.seat.routing_recommendation}`);
+  }
+
+  if (decision === 'dispatch_ready' && options.seat.active_workers >= options.seat.max_recommended_workers) {
+    decision = 'blocked_by_capability';
+    reasons.push('seat_at_worker_capacity');
+  }
+
+  if (decision === 'dispatch_ready' && requestedStrategy && strategy.unsupported && options.mode.execution.strategy_policy === 'required') {
+    decision = 'blocked_by_capability';
+    reasons.push('required_strategy_unsupported');
+  } else if (requestedStrategy && strategy.unsupported) {
+    warnings.push('requested_strategy_unsupported_downshift_allowed');
+  }
+
+  if (decision === 'dispatch_ready' && options.workflow.recommendation === 'block') {
+    if (isGrantOnlyBlock(options.workflow)) {
+      decision = 'hold_for_grant';
+      reasons.push('grant_ref_required');
+    } else if (
+      options.workflow.missing.includes('validation_refs')
+      || options.workflow.missing.includes('receipt_ref')
+    ) {
+      decision = 'blocked_by_validation';
+      reasons.push(...options.workflow.missing.filter((item) => item === 'validation_refs' || item === 'receipt_ref'));
+    } else {
+      decision = 'quarantine_hold';
+      profileHint = 'quarantine_hold';
+      reasons.push(...options.workflow.missing);
+    }
+  }
+
+  if (decision === 'dispatch_ready' && options.mode.execution.rubric_required && !options.sandboxReceipt) {
+    decision = 'blocked_by_validation';
+    reasons.push('sandbox_run_receipt_required');
+  }
+
+  if (decision === 'dispatch_ready' && sandboxAccepted === false) {
+    decision = 'blocked_by_validation';
+    reasons.push('sandbox_run_receipt_unexpected_outcomes');
+  }
+
+  if (decision === 'dispatch_ready' && options.mode.mode_type === 'deliberative') {
+    profileHint = 'sabbatical_improvement';
+  }
+
+  return {
+    schema: 'operational-dispatch-decision.v0',
+    task_ref: options.envelope.task_ref,
+    seat: options.seat.seat,
+    decision,
+    reasons: unique(reasons),
+    warnings: unique(warnings),
+    profile_hint: profileHint,
+    inputs: {
+      seat_readiness: {
+        operational_status: options.seat.operational_status,
+        routing_recommendation: options.seat.routing_recommendation,
+        capability_trusted: options.seat.capability_trusted,
+        model_tier: options.seat.model_tier,
+        effective_model_tier: options.seat.effective_model_tier,
+        active_workers: options.seat.active_workers,
+        max_recommended_workers: options.seat.max_recommended_workers,
+        is_stale: options.seat.is_stale,
+      },
+      workflow_check: {
+        mode_id: options.workflow.mode_id,
+        mode_type: options.workflow.mode_type,
+        recommendation: options.workflow.recommendation,
+        missing: options.workflow.missing,
+        warnings: options.workflow.warnings,
+      },
+      strategy: {
+        requested_strategy: requestedStrategy,
+        policy: options.mode.execution.strategy_policy,
+        supported: strategy.supported,
+        unsupported: strategy.unsupported,
+      },
+      rubric_receipt: {
+        receipt_id: options.sandboxReceipt?.receipt_id ?? null,
+        unexpected_outcomes: options.sandboxReceipt?.summary.unexpected_outcomes ?? null,
+        accepted: sandboxAccepted,
+      },
+    },
+    authority_boundary: {
+      can_dispatch: false,
+      can_authorize: false,
+      can_attach_grant: false,
+      can_execute: false,
+      consumer_is_engine: false,
+    },
+  };
+}