@kontextmind/kxm/scripts/assignment-run.d.mts

KXM local-first multi-agent orchestration and operator dashboard

export const ASSIGNMENT_SCHEMA: "kxm.assignment.v1";
export const PLAN_POINTER_SCHEMA: "kxm.plan-pointer.v1";
export const PLAN_POINTER_FILENAME: "plan-current.json";
export const COMPLETION_SCHEMA: "kxm.assignment-completion.v1";
export const REFUSAL_SCHEMA: "kxm.assignment-refusal.v1";
export const ASSIGNMENT_DISPATCH_SCHEMA: "kxm.assignment-dispatch.v1";
export const TELEMETRY_SCHEMA: "kxm.telemetry.v1";
export const RECORDING_RESOLUTION_SCHEMA: "kxm.assignment-recording-resolution.v1";
export const RUNNER_CODES: readonly string[];
export const VERIFY_WITNESS_ID: "verify";
export const VALIDATE_CI_WITNESS_ID: "validate-ci";
export const WITNESS_IDS: readonly string[];
export const FIXED_GATES: Readonly<{
  verify: readonly ["npm", "run", "verify"];
  "validate-ci": readonly ["npm", "run", "validate:ci"];
}>;
export const WITNESS_SCHEMA: "kxm.assignment-witness.v1";
export const WITNESS_LATEST_SCHEMA: "kxm.assignment-witness-latest.v1";
export const WITNESS_RESULTS: readonly string[];
export const WITNESS_CODES: readonly string[];
export const ACCEPTED_SCHEMA: "kxm.task-accepted.v1";
export const ACCEPTED_FILENAME: "accepted.json";
export const ACCEPTED_NOTE: string;
export const REQUIRED_ACCEPT_CRITICS: Readonly<Record<string, Readonly<{
  harness: string;
  model: string;
  role: string;
}>>>;
export function resolveRequiredCritics(policy: unknown): Readonly<Record<string, Readonly<{
  harness: string;
  model: string;
  role: string;
  vendor: string;
  route_id?: string;
}>>>;
export function getRosterPolicy(deps?: Record<string, unknown>): import("./roster-policy.mjs").RosterPolicy;
export const ASSIGNMENT_KINDS: readonly string[];
export const KIND_ROLES: Readonly<Record<string, string>>;
export const REVIEW_KINDS: readonly string[];
export const WRITER_KINDS: readonly string[];
export const CLEAN_BASE_KINDS: readonly string[];
export const READ_MECHANISMS: Readonly<Record<string, string>>;

export interface ValidatedAssignmentGit {
  readonly head: string;
  readonly index_tree: string;
  readonly clean: boolean;
}

export interface ValidatedAssignment {
  readonly schema: "kxm.assignment.v1";
  readonly task_id: string;
  readonly assignment_id: string;
  readonly rework_of?: string;
  readonly kind: string;
  readonly role: string;
  readonly harness: string;
  readonly model: string;
  readonly effort: string;
  readonly permission: string;
  readonly cwd: string;
  readonly task_dir: string;
  readonly record_dir: string;
  readonly base: Readonly<{ kind: "clean"; commit: string } | { kind: "staged"; commit: string; index_tree: string }>;
  readonly plan_ref: Readonly<
    | { kind: "current"; path: string; sha256: string; pointer_path: string; generation: number }
    | { kind: "bootstrap"; reason: string }
  >;
  readonly inputs: readonly Readonly<{ path: string; sha256: string }>[];
  readonly contract: Readonly<{
    boundary: string;
    deliverables: readonly string[];
    witness: Readonly<{ id: string }>;
    deferred: readonly string[];
  }>;
  readonly output_dir: string;
  readonly requested_output_dir?: string;
  readonly timeout_ms?: number;
  readonly max_turns?: number;
  readonly git: ValidatedAssignmentGit;
}

export function validateAssignmentManifest(manifest: unknown, deps?: {
  spawnSync?: typeof import("node:child_process").spawnSync;
  existsSync?: typeof import("node:fs").existsSync;
  readFileSync?: typeof import("node:fs").readFileSync;
  realpathSync?: typeof import("node:fs").realpathSync;
  lstatSync?: typeof import("node:fs").lstatSync;
  statSync?: typeof import("node:fs").statSync;
  rosterPolicy?: unknown;
  loadTrustedRosterPolicy?: () => unknown;
}): ValidatedAssignment;

export interface AssignmentCompletion {
  readonly schema: "kxm.assignment-completion.v1";
  readonly task_id: string;
  readonly assignment_id: string;
  readonly rework_of?: string;
  readonly kind: string;
  readonly role: string;
  readonly manifest: Readonly<{ sha256: string }>;
  readonly prompt: Readonly<{ sha256: string }>;
  readonly plan: Readonly<
    | { kind: "current"; path: string; sha256: string; pointer_path: string; generation: number }
    | { kind: "bootstrap"; reason: string }
  >;
  readonly route: Readonly<{
    harness: string;
    model: string;
    effort: string;
    permission: string;
    role: string;
  }>;
  readonly binding: Readonly<{
    task_dir: string;
    cwd: string;
    record_dir: string;
    output_dir: string;
  }>;
  readonly invocation: "thrown" | "returned";
  readonly candidate: Readonly<
    | { status: "recorded"; head: string; index_tree: string; clean: boolean }
    | { status: "unknown"; code: string }
  >;
  readonly recording: Readonly<
    | { status: "ok" }
    | {
      status: "failed";
      steps: Readonly<{
        candidate_snapshot: "ok" | "failed" | "skipped";
        sidecars: "ok" | "failed" | "skipped";
        routing_record: "ok" | "failed" | "skipped";
        telemetry: "ok" | "failed" | "skipped";
      }>;
      code: string;
    }
  >;
  readonly transport: Readonly<Record<string, unknown>>;
  readonly usage: Readonly<Record<string, unknown>>;
  readonly model_claim?: Readonly<Record<string, unknown>>;
  readonly sidecars: Readonly<Record<string, Readonly<{ path: string; bytes: number }>>>;
  readonly verification: Readonly<{ status: "not-run" }>;
  readonly critic: Readonly<
    | {
      kind: "none";
      reason: "not-review" | "transport-not-completed" | "candidate-unknown" | "candidate-changed" | "no-verdict";
    }
    | { kind: "review"; verdict: "PASS" | "BLOCK"; judged_tree: string; role: string }
  >;
  readonly attribution: Readonly<{ status: "unclassified" }>;
}

export function assignmentOutputSchema(kind: string): Record<string, unknown>;
export function renderAssignmentPrompt(validated: ValidatedAssignment, deps?: {
  existsSync?: typeof import("node:fs").existsSync;
  readFileSync?: typeof import("node:fs").readFileSync;
  statSync?: typeof import("node:fs").statSync;
}): string;
export function assignmentTelemetryPath(outputDir: string): string;
export function appendAssignmentTelemetry(completion: object, outputDir: string, deps?: object): boolean;
export function runAssignment(manifest: unknown, deps?: Record<string, unknown>): Promise<AssignmentCompletion>;
export function observeAssignment(outputDir: string, deps?: Record<string, unknown>): Promise<boolean>;

export interface AssignmentWitnessReceipt {
  readonly schema: "kxm.assignment-witness.v1";
  readonly receipt_id: string;
  readonly task_id: string;
  readonly assignment_id: string;
  readonly kind?: string;
  readonly recordedAt: string;
  readonly manifest: Readonly<{ path: string; sha256: string }>;
  readonly completion: Readonly<{ path: string; sha256: string }>;
  readonly plan: Readonly<
    | { kind: "current"; path?: string; sha256?: string; pointer_path?: string; generation?: number }
    | { kind: "bootstrap"; reason?: string }
  >;
  readonly binding: Readonly<{
    task_dir: string;
    cwd: string;
    record_dir: string;
  }>;
  readonly candidate: Readonly<{
    before?: Readonly<{ head: string; index_tree: string; clean: boolean } | { status: "unknown"; code: string }>;
    after?: Readonly<{ head: string; index_tree: string; clean: boolean } | { status: "unknown"; code: string }>;
  }>;
  readonly gates: readonly Readonly<{
    id: string;
    argv: readonly string[];
    shell: false;
    cwd: string;
    exitCode: number | null;
    signal: string | null;
    timedOut: boolean;
    durationMs: number;
    log: Readonly<{ path: string; bytes: number }>;
  }>[];
  readonly result: "passed" | "failed" | "refused";
  readonly code?: string;
  readonly startedAt: string;
  readonly finishedAt: string;
  readonly durationMs: number;
  readonly path?: string;
  readonly sha256?: string;
}

export function witnessAssignment(recordDir: string, deps?: Record<string, unknown>): Promise<AssignmentWitnessReceipt>;

export interface TaskAccepted {
  readonly schema: "kxm.task-accepted.v1";
  readonly task_id: string;
  readonly commit: string;
  readonly tree: string;
  readonly writer: Readonly<{
    assignment_id: string;
    record_dir: string;
    kind: string;
    completion: Readonly<{ path: string; sha256: string }>;
    manifest: Readonly<{ path: string; sha256: string }>;
    receipt: Readonly<{ id: string; path: string; sha256: string }>;
  }>;
  readonly plan: Readonly<{
    kind: "current";
    path: string;
    sha256: string;
    pointer_path: string;
    generation: number;
  }>;
  readonly critics: readonly Readonly<{
    kind: string;
    role: string;
    harness: string;
    model: string;
    assignment_id: string;
    record_dir: string;
    completion: Readonly<{ path: string; sha256: string }>;
    verdict: "PASS";
    judged_tree: string;
  }>[];
  readonly acceptedAt: string;
  readonly observed: Readonly<{
    pr?: Readonly<{ id: string; validated: false }>;
    ci?: Readonly<{ id: string; validated: false }>;
  }>;
  readonly note: string;
  readonly path?: string;
  readonly sha256?: string;
}

export function acceptAssignment(request: {
  taskDir: string;
  commit: string;
  recordDir: string;
  critics: readonly string[];
  observedPr?: string;
  observedCi?: string;
}, deps?: Record<string, unknown>): Promise<TaskAccepted>;

export interface AssignmentRecordingResolution {
  readonly schema: "kxm.assignment-recording-resolution.v1";
  readonly task_id: string;
  readonly assignment_id: string;
  readonly resolvedAt?: string;
  readonly completion_sha256: string;
  readonly steps: Readonly<{
    candidate_snapshot: "ok" | "failed" | "skipped";
    sidecars: "ok" | "failed" | "skipped";
    routing_record: "ok" | "failed" | "skipped";
    telemetry: "ok" | "failed" | "skipped";
  }>;
}

export function main(argv?: string[], io?: {
  stdin: NodeJS.ReadableStream;
  stdout: NodeJS.WritableStream;
  stderr: NodeJS.WritableStream;
  spawnSync?: typeof import("node:child_process").spawnSync;
  env?: NodeJS.ProcessEnv;
  now?: () => number;
}): Promise<AssignmentCompletion | AssignmentRecordingResolution | AssignmentWitnessReceipt | TaskAccepted | CostObservationReceipt | AttributionPointer | ReturnType<typeof changeReport> | ReturnType<typeof writeCurrentPlan>>;

export const COST_OBSERVATION_SCHEMA: "kxm.cost-observation.v1";
export const ATTRIBUTION_SCHEMA: "kxm.assignment-attribution.v1";
export const ATTRIBUTION_CLASSES: readonly string[];
export interface CostObservation {
  schema: "kxm.cost-observation.v1";
  task_id: string;
  assignment_id: string;
  kind: string;
  route: { harness: string; provider: string; model: string; effort: string };
  status: "completed" | "failed" | "interrupted" | "unknown";
  timing: { started_at: string | null; finished_at: string | null; latency_ms: number | null };
  usage: {
    input_tokens: number | null;
    output_tokens: number | null;
    cache_read_tokens: number | null;
    cache_write_tokens: number | null;
    reasoning_tokens: number | null;
    context_tokens: number | null;
    token_basis: "cumulative";
    cost_basis: "provider-reported" | "list" | "unmetered" | "unknown";
    cost_usd: number | null;
    estimate_usd: number | null;
    partial: boolean;
  };
  sources: Array<{ path: string; sha256: string }>;
  note: string;
  accounting: { included: boolean; reason: string };
  cost_only: true;
  rework: boolean | null;
  rework_of?: string;
}
export interface CostObservationReceipt {
  schema: "kxm.cost-observation.v1";
  task_id: string;
  assignment_id: string;
  cost_only: true;
  path: string;
  sha256: string;
}
export interface AttributionPointer {
  schema: "kxm.assignment-attribution.v1";
  id: string;
  classification: "orchestration" | "model" | "environment" | "unclassified";
  sha256: string;
}
export function observeAssignmentCost(request: { taskDir: string; observation: CostObservation }, deps?: Record<string, unknown>): CostObservationReceipt;
export function attributeAssignment(request: { taskDir: string; recordDir: string; classification: string; explanation: string }, deps?: Record<string, unknown>): AttributionPointer;

export const CHANGE_REPORT_SCHEMA: "kxm.change-report.v1";
export function changeReport(request: { taskDir: string }, deps?: Record<string, unknown>): {
  schema: "kxm.change-report.v1";
  task_id: string;
  assignments: Array<Record<string, any>>;
  totals: Record<string, any>;
  ignored: Array<{ name: string; reason: string }>;
  issues: Array<Record<string, string>>;
  acceptance: Record<string, any> | null;
  effort_observations: Array<Record<string, any>>;
  ranking: "not-ranked";
  orchestration_usage: "unavailable";
};
export const ROUTING_EXPORT_SCHEMA: "kxm.assignment-routing-export.v1";
export function exportAssignmentRoutingRecords(request: { taskDir: string }, deps?: Record<string, unknown>): {
  schema: "kxm.assignment-routing-export.v1";
  task_id: string;
  records: Array<Record<string, any>>;
  skipped: Array<{ assignment_id: string | null; reason: "acceptance_record_invalid" | "no_routing_record" | "routing_record_invalid" | "manifest_invalid" }>;
};
export function writeCurrentPlan(request: {
  taskDir: string; plan: string; sha256: string; baseCommit: string; expectedGeneration: number; settledDecisions?: string[];
}, deps?: Record<string, unknown>): {
  schema: "kxm.plan-pointer.v1";
  task_id: string;
  generation: number;
  plan_path: string;
  plan_sha256: string;
  base_commit: string;
  settled_decisions: string[];
  supersedes: Array<Record<string, unknown>>;
  updated_at: string;
};