cc-codeconductor 1.7.2 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  **Stop prompting. Start orchestrating.**
4
4
 
5
- [![Socket Badge](https://badge.socket.dev/npm/package/cc-codeconductor/1.7.2)](https://badge.socket.dev/npm/package/cc-codeconductor/1.7.2)
5
+ [![Socket Badge](https://badge.socket.dev/npm/package/cc-codeconductor/1.9.0)](https://badge.socket.dev/npm/package/cc-codeconductor/1.9.0)
6
6
  [![Website](https://img.shields.io/badge/website-codeconductor.appsutiles.dev-0A66C2)](https://codeconductor.appsutiles.dev/)
7
7
 
8
8
  CodeConductor is an open-source framework for building structured, reproducible
@@ -16,7 +16,7 @@ contracts, task cards, and risk-based routing.
16
16
  >
17
17
  > ## Current Scope
18
18
  >
19
- > Published package is **1.7.2** (current stable line: **1.7.x**). Limitations
19
+ > Published package is **1.9.0** (current stable line: **1.9.x**). Limitations
20
20
  > matrix:
21
21
  > [docs/current-status.md](docs/current-status.md). This repository:
22
22
  > `bun run dev …` (not `npx`) while iterating.
@@ -28,7 +28,7 @@ contracts, task cards, and risk-based routing.
28
28
  > [post-v1.6.1 guide](docs/post-v1.6.1.md) for the earlier commit range and
29
29
  > upgrade steps.
30
30
  >
31
- > Shipped in the 1.7.x stable line:
31
+ > Shipped in the 1.9.x stable line:
32
32
  >
33
33
  > - `npx cc-codeconductor setup --target <target> --yes` — onboarding flow
34
34
  > - `npx cc-codeconductor init` — detects project stack, writes
@@ -340,14 +340,14 @@ Task Card → Risk Classification → Routing Policy → Conductor Agent → Del
340
340
 
341
341
  ## Supply chain
342
342
 
343
- Published **1.7.2** declares two production dependencies (`package.json`
343
+ Published **1.9.0** declares two production dependencies (`package.json`
344
344
  `dependencies`; same on
345
345
  [npm](https://www.npmjs.com/package/cc-codeconductor)). Neither has further
346
346
  npm transitive dependencies.
347
347
 
348
348
  ```mermaid
349
349
  graph LR
350
- cc["cc-codeconductor@1.7.2"]
350
+ cc["cc-codeconductor@1.9.0"]
351
351
  zod["zod@^3.23.8"]
352
352
  yaml["yaml@^2.4.5"]
353
353
  cc --> zod
@@ -876,7 +876,7 @@ codeconductor/
876
876
 
877
877
  ## Roadmap
878
878
 
879
- Published package: **1.7.x (current stable: 1.7.2)**. Remaining gaps (sandbox, policy compiler, full
879
+ Published package: **1.9.x (current stable: 1.9.0)**. Remaining gaps (sandbox, policy compiler, full
880
880
  stack-specific asset pruning): [docs/current-status.md](docs/current-status.md).
881
881
  Release history: [CHANGELOG.md](CHANGELOG.md).
882
882
 
@@ -14,3 +14,21 @@ export declare function loadGoal(projectRoot: string): Promise<Result<GoalGraphI
14
14
  * Loads the graph, finds the task by ID, sets status to 'blocked', and writes back.
15
15
  */
16
16
  export declare function markTaskBlocked(projectRoot: string, taskId: string, reason: string): Promise<Result<void, Error>>;
17
+ /** Consecutive failures before the breaker trips and freezes the task. */
18
+ export declare const BREAKER_TRIP_THRESHOLD = 3;
19
+ export interface StrikeResult {
20
+ readonly taskId: string;
21
+ readonly failures: number;
22
+ readonly tripped: boolean;
23
+ }
24
+ /**
25
+ * Record one failure strike. The breaker trips on the third consecutive
26
+ * strike: the task is blocked and frozen with an escalation reason, and
27
+ * dependents propagate to blocked. Strikes on frozen tasks are idempotent;
28
+ * strikes on done tasks are rejected. Counter resets only via unfreezeTask.
29
+ */
30
+ export declare function recordTaskStrike(projectRoot: string, taskId: string, reason: string): Promise<Result<StrikeResult, Error>>;
31
+ /**
32
+ * Recovery counterpart: clear the breaker trip and re-queue the task.
33
+ */
34
+ export declare function unfreezeTask(projectRoot: string, taskId: string): Promise<Result<void, Error>>;
@@ -0,0 +1,75 @@
1
+ /**
2
+ * OS-agnostic agent hook policy. No bash, no jq, no GNU date.
3
+ * Hosts call `cc-codeconductor hook <event>` via Node.
4
+ */
5
+ export type AgentRole = 'tester' | 'implementer' | 'reviewer' | 'architect';
6
+ export interface RoleAccessResult {
7
+ allowed: boolean;
8
+ reason?: string;
9
+ }
10
+ export declare function evaluateRoleAccess(role: AgentRole, filePath: string, protectedDirs?: string[]): RoleAccessResult;
11
+ /**
12
+ * Deny-first TaskCard scope check for file writes.
13
+ *
14
+ * Matching mirrors the scorecard scope audit (substring after stripping
15
+ * `**`). An empty scope list is fail-open: no restriction configured.
16
+ */
17
+ export declare function scopeMatchesFile(filePath: string, scopeFiles: readonly string[]): boolean;
18
+ export declare function evaluateScopeAccess(filePath: string, scopeFiles: readonly string[]): RoleAccessResult;
19
+ export type DispatchMode = 'full' | 'surgical-fix' | 'refactor-only' | 'test-add' | 'scaffold' | 'rename-move' | 'dep-bump';
20
+ export declare const DISPATCH_MODES: readonly DispatchMode[];
21
+ export declare function isDispatchMode(raw: unknown): raw is DispatchMode;
22
+ export interface DispatchInput {
23
+ readonly filePath?: string;
24
+ readonly command?: string;
25
+ readonly scopeFiles?: readonly string[];
26
+ /** File existence resolved by the caller; unknown fails closed where it matters. */
27
+ readonly exists?: boolean;
28
+ }
29
+ /**
30
+ * Deny-first dispatch-mode write profiles for leaf implementers.
31
+ * Judges file writes; bare commands fall through to the command safety net,
32
+ * except rename-move which only permits `git mv`.
33
+ */
34
+ export declare function evaluateDispatchMode(mode: DispatchMode, input: DispatchInput): RoleAccessResult;
35
+ /**
36
+ * Leaf task-deny: leaf agents (no sub-delegation) cannot invoke delegation tools.
37
+ */
38
+ export declare function evaluateLeafTaskAccess(toolName: string | undefined): RoleAccessResult;
39
+ export type HookEvent = 'pre-tool' | 'post-tool' | 'session-start' | 'session-end' | 'subagent-stop' | 'stop';
40
+ export type HookFormat = 'claude' | 'agy' | 'muse';
41
+ export type HookAction = 'allow' | 'ask' | 'deny';
42
+ /** All events accepted by `cc-codeconductor hook <event>` and invoke-hook.cjs. */
43
+ export declare const HOOK_EVENTS: readonly HookEvent[];
44
+ export interface HookVerdict {
45
+ readonly action: HookAction;
46
+ readonly message: string;
47
+ readonly exitCode: number;
48
+ }
49
+ export interface PreToolInput {
50
+ readonly command?: string;
51
+ readonly filePath?: string;
52
+ readonly toolName?: string;
53
+ readonly scopeFiles?: readonly string[];
54
+ readonly dispatchMode?: DispatchMode;
55
+ readonly leaf?: boolean;
56
+ readonly exists?: boolean;
57
+ }
58
+ export declare function normalizeCommand(raw: string): string;
59
+ /** Treat `git.exe` / `C:\...\git.exe` as `git` for policy matching. */
60
+ export declare function stripGitBinary(command: string): string;
61
+ export declare function evaluatePath(filePath: string): HookVerdict;
62
+ export declare function evaluateCommand(rawCommand: string): HookVerdict;
63
+ export declare function evaluatePreTool(input: PreToolInput): HookVerdict;
64
+ export declare function formatHookOutput(verdict: HookVerdict, format: HookFormat): string;
65
+ export declare function claudeExitCode(verdict: HookVerdict): number;
66
+ /**
67
+ * Parse a Muse PreToolUse payload. Muse speaks the Claude-compatible hook
68
+ * protocol (`hook_event_name` / `tool_name` / `tool_input` over stdin), so
69
+ * this shares the field extraction — kept as its own function so future
70
+ * Muse-only fields have a home without disturbing the Claude path.
71
+ */
72
+ export declare function parseMusePayload(stdinText: string): PreToolInput;
73
+ export declare function parseAgyPayload(raw: string): PreToolInput;
74
+ export declare function parseClaudePayload(raw: string): PreToolInput;
75
+ export declare function formatSessionStart(lines: readonly string[]): string;
@@ -1,6 +1,7 @@
1
1
  import type { CanonicalTaskCardInput, GoalGraphInput, GoalTaskInput, OperationalStateInput } from '../../validation/schemas';
2
2
  import { type Result } from '../../utils/result';
3
3
  import type { CommandEnvelopeInput } from '../../validation/schemas';
4
+ import { type DispatchMode } from '../hooks/hook-runner';
4
5
  /**
5
6
  * Undo a task status change and restore the operational state captured before
6
7
  * it. Used when a later step fails, so a task is never left half-transitioned.
@@ -18,9 +19,16 @@ export interface OrchestratorNextResult {
18
19
  task: CanonicalTaskCardInput;
19
20
  envelope: CommandEnvelopeInput;
20
21
  readyCount: number;
22
+ dispatchMode: DispatchMode;
21
23
  }
22
- export declare function getNextTask(projectRoot: string, projectName: string): Promise<Result<OrchestratorNextResult, Error>>;
23
- export declare function claimNextTask(projectRoot: string, projectName: string): Promise<Result<OrchestratorNextResult, Error>>;
24
- export declare function startTask(projectRoot: string, taskId: string, agent?: string): Promise<Result<void, Error>>;
24
+ /**
25
+ * Dispatch mode derived from the goal task type. The orchestrator clears
26
+ * the task's inferred target files against this mode before dispatch,
27
+ * closing the loop with the hook layer (`hook pre-tool --dispatch`).
28
+ */
29
+ export declare function taskTypeToDispatchMode(type: GoalTaskInput['type']): DispatchMode;
30
+ export declare function getNextTask(projectRoot: string, projectName: string, dispatchMode?: DispatchMode): Promise<Result<OrchestratorNextResult, Error>>;
31
+ export declare function claimNextTask(projectRoot: string, projectName: string, dispatchMode?: DispatchMode): Promise<Result<OrchestratorNextResult, Error>>;
32
+ export declare function startTask(projectRoot: string, taskId: string, agent?: string, dispatchMode?: DispatchMode): Promise<Result<void, Error>>;
25
33
  export declare function completeTask(projectRoot: string, taskId: string, evidenceIds?: string[]): Promise<Result<void, Error>>;
26
34
  export declare function formatGoalStatus(graph: GoalGraphInput): string;
@@ -0,0 +1,55 @@
1
+ import { type HarnessTelemetryEvent, type PrivacyMode } from './schema';
2
+ export interface ClaudeHookEnvelope {
3
+ session_id?: string;
4
+ sessionId?: string;
5
+ hook_event_name?: string;
6
+ agent_id?: string;
7
+ agent_type?: string;
8
+ agent_transcript_path?: string;
9
+ transcript_path?: string;
10
+ cwd?: string;
11
+ tool_name?: string;
12
+ tool_input?: Record<string, unknown>;
13
+ tool_response?: unknown;
14
+ /** Present on PostToolUseFailure — never store its content. */
15
+ error?: unknown;
16
+ /** Never stored (privacy §7). */
17
+ last_assistant_message?: unknown;
18
+ }
19
+ export declare function parseClaudeHookEnvelope(raw: string): ClaudeHookEnvelope;
20
+ export declare function runIdFromSession(sessionId: string | null | undefined): string;
21
+ export declare function formatRetryReason(reason: string, privacy: PrivacyMode): string;
22
+ /** SubagentStop → agent.end (role = agent_type). */
23
+ export declare function emitAgentEndFromSubagentStop(projectRoot: string, envelope: ClaudeHookEnvelope): Promise<HarnessTelemetryEvent>;
24
+ /** SessionEnd → run.end (transcript read deferred to M3). */
25
+ export declare function emitRunEndFromSessionEnd(projectRoot: string, envelope: ClaudeHookEnvelope): Promise<HarnessTelemetryEvent>;
26
+ /**
27
+ * Stop — session/turn boundary. Does not store last_assistant_message.
28
+ * Emits nothing beyond acknowledging the hook (keeps Stop async and cheap).
29
+ * Subagent agent.end comes from SubagentStop; run.end from SessionEnd.
30
+ */
31
+ export declare function handleStopHook(_projectRoot: string, _envelope: ClaudeHookEnvelope): Promise<void>;
32
+ /** post-tool: optional verification heuristic when the tool looks like a test run. */
33
+ export declare function emitPostToolTelemetry(projectRoot: string, envelope: ClaudeHookEnvelope, options?: {
34
+ failed?: boolean;
35
+ }): Promise<HarnessTelemetryEvent | null>;
36
+ export declare function emitLoopIteration(projectRoot: string, input: {
37
+ runId: string;
38
+ taskId?: string | null;
39
+ iteration: number;
40
+ maxIterations: number;
41
+ }): Promise<void>;
42
+ export declare function emitLoopRetry(projectRoot: string, input: {
43
+ runId: string;
44
+ taskId?: string | null;
45
+ iteration: number;
46
+ maxIterations: number;
47
+ feedback: string;
48
+ }): Promise<void>;
49
+ export declare function emitVerificationGate(projectRoot: string, input: {
50
+ runId: string;
51
+ taskId: string;
52
+ gate: string;
53
+ passed: boolean;
54
+ durationMs?: number | null;
55
+ }): Promise<void>;
@@ -0,0 +1,94 @@
1
+ export declare const HARNESS_TELEMETRY_SCHEMA: "harness-telemetry/v1";
2
+ export declare const HARNESS_TELEMETRY_SCHEMA_PATH: string;
3
+ export type HarnessName = 'codeconductor' | 'microsdd';
4
+ export type TelemetryEventName = 'run.start' | 'run.end' | 'task.start' | 'task.end' | 'agent.end' | 'model.call' | 'verification' | 'retry' | 'iteration';
5
+ export type HostName = 'claude-code' | 'codex' | 'opencode' | 'openrouter-direct' | 'other';
6
+ export type HostMode = 'headless' | 'interactive';
7
+ export type ModelProvider = 'anthropic' | 'openrouter' | 'openai' | 'other';
8
+ export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
9
+ export type CostBasis = 'provider-billed' | 'host-estimate' | 'pricing-table' | 'unknown' | 'none';
10
+ export type UsageSource = 'cc-json' | 'cc-otel' | 'cc-transcript' | 'openrouter-usage' | 'codex-json' | 'harness' | 'none';
11
+ export type Reliability = 'high' | 'medium' | 'low';
12
+ export type PrivacyMode = 'standard' | 'strict';
13
+ export type OutcomeStatus = 'done' | 'failed' | 'escalated' | 'aborted';
14
+ export interface TelemetryUsage {
15
+ input: number | null;
16
+ output: number | null;
17
+ cacheRead: number | null;
18
+ cacheWrite: number | null;
19
+ reasoning: number | null;
20
+ calls: number | null;
21
+ apiRetries: number | null;
22
+ }
23
+ export interface TelemetryCost {
24
+ usd: number | null;
25
+ basis: CostBasis | null;
26
+ pricingVersion: string | null;
27
+ isRealSpend: boolean | null;
28
+ }
29
+ export interface HarnessTelemetryEvent {
30
+ schema: typeof HARNESS_TELEMETRY_SCHEMA;
31
+ ts: string;
32
+ harness: {
33
+ name: HarnessName;
34
+ version: string | null;
35
+ commit: string | null;
36
+ promptCompilerVersion: string | null;
37
+ promptFingerprint: string | null;
38
+ };
39
+ runId: string;
40
+ taskId: string | null;
41
+ agent: {
42
+ role: string | null;
43
+ agentId: string | null;
44
+ } | null;
45
+ event: TelemetryEventName;
46
+ host: {
47
+ name: HostName | null;
48
+ version: string | null;
49
+ mode: HostMode | null;
50
+ } | null;
51
+ model: {
52
+ id: string | null;
53
+ provider: ModelProvider | null;
54
+ effort: EffortLevel | null;
55
+ } | null;
56
+ usage: TelemetryUsage | null;
57
+ cost: TelemetryCost | null;
58
+ loop: {
59
+ iteration: number | null;
60
+ retryReason: string | null;
61
+ maxIterations: number | null;
62
+ } | null;
63
+ verification: {
64
+ gate: string | null;
65
+ passed: boolean | null;
66
+ durationMs: number | null;
67
+ } | null;
68
+ durationMs: number | null;
69
+ outcome: {
70
+ status: OutcomeStatus | null;
71
+ firstTry: boolean | null;
72
+ } | null;
73
+ source: {
74
+ usage: UsageSource | null;
75
+ reliability: Reliability | null;
76
+ } | null;
77
+ privacy: PrivacyMode | null;
78
+ }
79
+ export declare function emptyUsage(): TelemetryUsage;
80
+ export declare function emptyCost(): TelemetryCost;
81
+ /** Coerce a missing measurement to null; never invent a zero. */
82
+ export declare function nullableNumber(value: unknown): number | null;
83
+ export declare function isHarnessTelemetryEvent(value: unknown): value is HarnessTelemetryEvent;
84
+ export declare function assertHarnessTelemetryEvent(value: unknown): HarnessTelemetryEvent;
85
+ export declare function loadHarnessTelemetryJsonSchema(): Promise<unknown>;
86
+ export declare function createBaseEvent(input: {
87
+ runId: string;
88
+ event: TelemetryEventName;
89
+ harnessName?: HarnessName;
90
+ harnessVersion?: string | null;
91
+ harnessCommit?: string | null;
92
+ ts?: string;
93
+ privacy?: PrivacyMode | null;
94
+ }): HarnessTelemetryEvent;
@@ -0,0 +1,43 @@
1
+ import { type Result } from '../../utils/result';
2
+ import { type HarnessTelemetryEvent, type PrivacyMode } from './schema';
3
+ export interface TelemetryWriteOptions {
4
+ /** When false, nothing is written. Defaults to resolved report.history. */
5
+ history?: boolean;
6
+ privacy?: PrivacyMode;
7
+ }
8
+ export interface ReportSettings {
9
+ level: 'off' | 'minimal' | 'detailed';
10
+ history: boolean;
11
+ privacy: PrivacyMode;
12
+ }
13
+ /**
14
+ * Resolve report settings. Any history:false wins (env, project, or options).
15
+ * Env: CC_REPORT_HISTORY=false | CC_REPORT=off (does not itself disable history).
16
+ */
17
+ export declare function resolveReportSettings(projectRoot: string, overrides?: Partial<ReportSettings>): Promise<ReportSettings>;
18
+ /** Apply §7 privacy scrubbing. Does not store prompts, responses, diffs, or tool output. */
19
+ export declare function applyPrivacy(event: HarnessTelemetryEvent, privacy: PrivacyMode): HarnessTelemetryEvent;
20
+ export declare function ensureTelemetryDirs(projectRoot: string): Promise<{
21
+ telemetryDir: string;
22
+ reportsDir: string;
23
+ }>;
24
+ export declare function telemetryRunPath(projectRoot: string, runId: string): string;
25
+ export declare function reportsRunsPath(projectRoot: string): string;
26
+ /**
27
+ * Append a telemetry event. No-op when history is false.
28
+ */
29
+ export declare function appendTelemetryEvent(projectRoot: string, event: HarnessTelemetryEvent, options?: TelemetryWriteOptions): Promise<Result<{
30
+ written: boolean;
31
+ path: string | null;
32
+ }, Error>>;
33
+ /**
34
+ * Append a run-report line to .codeconductor/reports/runs.jsonl.
35
+ * No-op when history is false.
36
+ */
37
+ export declare function appendRunReport(projectRoot: string, report: Record<string, unknown>, options?: TelemetryWriteOptions): Promise<Result<{
38
+ written: boolean;
39
+ }, Error>>;
40
+ export declare function readTelemetryRun(projectRoot: string, runId: string): Promise<Result<HarnessTelemetryEvent[], Error>>;
41
+ export declare function listTelemetryRunIds(projectRoot: string): Promise<string[]>;
42
+ /** Delete project telemetry + reports history (local only). */
43
+ export declare function purgeTelemetry(projectRoot: string, scope?: 'project' | 'all'): Promise<Result<void, Error>>;