@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/domains/safety/decision-presentation.ts

@@ -0,0 +1,268 @@
+import type { ActionClass } from "./action-classifier.js";
+import type { AutonomyExposure } from "./autonomy.js";
+
+/** Closed consequence categories used only to explain an already-made decision request. */
+export const DECISION_TIERS = ["conversation", "workspace", "outward", "safety-net", "system", "worker"] as const;
+
+export type DecisionTier = (typeof DECISION_TIERS)[number];
+export type DecisionSemanticToken = "accent" | "action" | "warning";
+export type DecisionRequestKind = "question" | "permission";
+export type DecisionAffectedScope = "conversation" | "workspace" | "outward" | "system";
+export type DecisionReversibility = "reversible" | "limited" | "unknown";
+export type DecisionAuthorityEffect = "records-answer" | "grants-once";
+export type DecisionActionId = "record-answer" | "cancel" | "approve-once" | "deny" | "stop";
+
+export type DecisionAxis =
+	| { kind: "answer" }
+	| { kind: "autonomy"; level: string }
+	| { kind: "safety-net"; ruleId: string };
+
+export type DecisionOrigin = { kind: "main" } | { kind: "worker"; agentId: string; runId: string };
+
+/**
+ * Facts the host has already authenticated or derived from enforced policy.
+ * No model-authored title, question, reason, summary, or option label belongs
+ * here, so prose has no path to the tier selection.
+ */
+export interface TrustedDecisionFacts {
+	requestKind: DecisionRequestKind;
+	axis: DecisionAxis;
+	exposure: AutonomyExposure;
+	affectedScope: DecisionAffectedScope;
+	reversibility: DecisionReversibility;
+	origin: DecisionOrigin;
+	authorityEffect: DecisionAuthorityEffect;
+	tool?: string;
+	actionClass?: ActionClass;
+}
+
+export interface DecisionPresentationAction {
+	id: DecisionActionId;
+	label: string;
+	consequence: string;
+}
+
+/**
+ * This projection contains display data only. Registry admission and interview
+ * settlement never consume it, and it contains no allow, deny, or autonomy
+ * disposition that an execution layer could mistake for authority.
+ */
+export interface DecisionPresentation {
+	tier: DecisionTier;
+	tierLabel: string;
+	title: string;
+	semanticToken: DecisionSemanticToken;
+	authorizationCopy: string;
+	consequenceCopy: string;
+	reversibilityCopy: string;
+	requestedByCopy: string;
+	requiredActions: ReadonlyArray<DecisionPresentationAction>;
+}
+
+const ACTION_CLASSES = new Set<ActionClass>([
+	"read",
+	"write",
+	"execute",
+	"dispatch",
+	"system_modify",
+	"git_destructive",
+	"unknown",
+]);
+
+/** Unknown or malformed action classes classify conservatively as unknown. */
+export function decisionActionClass(value: unknown): ActionClass {
+	return typeof value === "string" && ACTION_CLASSES.has(value as ActionClass) ? (value as ActionClass) : "unknown";
+}
+
+function actionConsequence(actionClass: ActionClass): {
+	affectedScope: DecisionAffectedScope;
+	reversibility: DecisionReversibility;
+} {
+	switch (actionClass) {
+		case "read":
+			return { affectedScope: "workspace", reversibility: "reversible" };
+		case "write":
+			return { affectedScope: "workspace", reversibility: "reversible" };
+		case "execute":
+		case "dispatch":
+			return { affectedScope: "workspace", reversibility: "limited" };
+		case "system_modify":
+		case "git_destructive":
+		case "unknown":
+			return { affectedScope: "system", reversibility: "unknown" };
+	}
+}
+
+export function decisionFactsForPermission(input: {
+	tool: string;
+	actionClass: ActionClass;
+	axis: Exclude<DecisionAxis, { kind: "answer" }>;
+	origin: DecisionOrigin;
+	exposure?: AutonomyExposure;
+}): TrustedDecisionFacts {
+	const exposure = input.exposure ?? "local";
+	const consequence = actionConsequence(input.actionClass);
+	return {
+		requestKind: "permission",
+		axis: input.axis,
+		exposure,
+		affectedScope: exposure === "outward" ? "outward" : consequence.affectedScope,
+		reversibility: exposure === "outward" ? "limited" : consequence.reversibility,
+		origin: input.origin,
+		authorityEffect: "grants-once",
+		tool: input.tool,
+		actionClass: input.actionClass,
+	};
+}
+
+export function decisionFactsForAnswer(exposure: AutonomyExposure): TrustedDecisionFacts {
+	return {
+		requestKind: "question",
+		axis: { kind: "answer" },
+		exposure,
+		affectedScope: exposure === "outward" ? "outward" : "conversation",
+		reversibility: exposure === "outward" ? "limited" : "reversible",
+		origin: { kind: "main" },
+		authorityEffect: "records-answer",
+	};
+}
+
+function classifyTier(facts: TrustedDecisionFacts): DecisionTier {
+	if (facts.origin.kind === "worker") return "worker";
+	if (facts.affectedScope === "system") return "system";
+	if (facts.exposure === "outward" || facts.affectedScope === "outward") return "outward";
+	if (facts.axis.kind === "safety-net") return "safety-net";
+	if (facts.authorityEffect === "grants-once") return "workspace";
+	return "conversation";
+}
+
+function tierIdentity(tier: DecisionTier): {
+	tierLabel: string;
+	title: string;
+	semanticToken: DecisionSemanticToken;
+} {
+	switch (tier) {
+		case "conversation":
+			return { tierLabel: "Conversational answer", title: "Answer a question", semanticToken: "accent" };
+		case "workspace":
+			return { tierLabel: "Workspace authority", title: "Approve workspace action", semanticToken: "action" };
+		case "outward":
+			return { tierLabel: "Outward consequence", title: "Confirm outward consequence", semanticToken: "warning" };
+		case "safety-net":
+			return { tierLabel: "Safety-net confirmation", title: "Safety-net confirmation", semanticToken: "warning" };
+		case "system":
+			return { tierLabel: "System change", title: "Approve system change", semanticToken: "warning" };
+		case "worker":
+			return { tierLabel: "Worker escalation", title: "Worker needs approval", semanticToken: "action" };
+	}
+}
+
+function requestedByCopy(facts: TrustedDecisionFacts): string {
+	const requester =
+		facts.origin.kind === "worker" ? `worker ${facts.origin.agentId} (run ${facts.origin.runId})` : "main agent";
+	if (facts.axis.kind === "answer") return requester;
+	if (facts.axis.kind === "safety-net") return `${requester} through safety-net rail ${facts.axis.ruleId}`;
+	return `${requester} through autonomy level (${facts.axis.level})`;
+}
+
+function authorizationCopy(facts: TrustedDecisionFacts): string {
+	if (facts.authorityEffect === "records-answer") {
+		return facts.exposure === "outward"
+			? "Your response records an answer about an outward step. It does not publish or send anything by itself."
+			: "Your response records an answer for this interview. It grants no tool authority.";
+	}
+	const tool = facts.tool ?? "the presented tool";
+	const actionClass = facts.actionClass ?? "unknown";
+	if (tool === "ask_user" && facts.exposure === "outward") {
+		return "Approval opens this one outward-decision interview. It does not publish or send anything by itself.";
+	}
+	return `Approval authorizes one ${actionClass} call to ${tool}. It does not change the autonomy level.`;
+}
+
+function consequenceCopy(facts: TrustedDecisionFacts, tier: DecisionTier): string {
+	switch (tier) {
+		case "conversation":
+			return "The answer stays in this session's decision record.";
+		case "workspace":
+			return facts.actionClass === "read"
+				? "The call reads within the workspace without mutating it."
+				: "The call can affect files or processes inside the workspace.";
+		case "outward":
+			return "The resulting step can reach people or systems outside the workspace.";
+		case "safety-net":
+			return "An always-on safety-net rail requires a one-shot operator decision before this call can run.";
+		case "system":
+			return "The call can change state outside the workspace or state the classifier cannot safely bound.";
+		case "worker":
+			return "A dispatched worker is parked. Your answer returns only to that run's exact request.";
+	}
+}
+
+function reversibilityCopy(facts: TrustedDecisionFacts): string {
+	if (facts.requestKind === "question") {
+		return facts.reversibility === "reversible"
+			? "Reversible: yes. The recorded answer can be superseded later."
+			: "Reversible: not guaranteed. An outward step that later uses this answer may have lasting effects.";
+	}
+	if (facts.actionClass === "read" && facts.reversibility === "reversible") {
+		return "Reversible: yes. This call does not mutate the workspace.";
+	}
+	switch (facts.reversibility) {
+		case "reversible":
+			return "Reversible: yes. Workspace changes can be reviewed and reverted.";
+		case "limited":
+			return "Reversible: not guaranteed. Effects that already ran or reached an outward system may remain.";
+		case "unknown":
+			return "Reversible: unknown. Treat the effect as not safely reversible.";
+	}
+}
+
+function requiredActions(facts: TrustedDecisionFacts, tier: DecisionTier): ReadonlyArray<DecisionPresentationAction> {
+	if (facts.authorityEffect === "records-answer") {
+		return [
+			{
+				id: "record-answer",
+				label: facts.exposure === "outward" ? "Record outward answer" : "Record answer",
+				consequence: "Records the selected or typed answer without granting tool authority.",
+			},
+			{ id: "cancel", label: "Cancel", consequence: "Closes the interview without recording an answer for this round." },
+		];
+	}
+	const approveLabel =
+		tier === "system"
+			? "Approve system change once"
+			: tier === "safety-net"
+				? "Approve guarded action once"
+				: tier === "worker"
+					? "Approve worker request once"
+					: tier === "outward"
+						? "Approve outward decision once"
+						: "Approve workspace action once";
+	const stopConsequence =
+		facts.origin.kind === "worker"
+			? "Denies this worker request and ends the active main-agent turn. Other worker requests retain their timeout policy."
+			: "Denies every parked request from this turn and ends the run.";
+	return [
+		{
+			id: "approve-once",
+			label: approveLabel,
+			consequence: "Runs only the presented request and does not change the autonomy level.",
+		},
+		{ id: "deny", label: "Deny this request", consequence: "Denies only the presented request and advances the queue." },
+		{ id: "stop", label: "Deny and stop", consequence: stopConsequence },
+	];
+}
+
+/** Pure presentation classifier. It performs no I/O and has no execution authority. */
+export function classifyDecisionPresentation(facts: TrustedDecisionFacts): DecisionPresentation {
+	const tier = classifyTier(facts);
+	return {
+		tier,
+		...tierIdentity(tier),
+		authorizationCopy: authorizationCopy(facts),
+		consequenceCopy: consequenceCopy(facts, tier),
+		reversibilityCopy: reversibilityCopy(facts),
+		requestedByCopy: requestedByCopy(facts),
+		requiredActions: requiredActions(facts, tier),
+	};
+}

package/src/domains/safety/redaction.ts

@@ -0,0 +1,73 @@
+/**
+ * Display-time secret redaction for tool arguments.
+ *
+ * Two surfaces need the same rules and must not drift. The transcript's tool
+ * renderer projects a call's arguments for the operator's own screen, and the
+ * worker tool-admission seam composes a bounded action descriptor that crosses
+ * the NDJSON stdout boundary. A credential that one of them scrubs and the
+ * other prints is a leak, so the patterns live here and both import them.
+ *
+ * This is presentation only. Execution, receipts, and the safety verdict all
+ * keep the original argument values; nothing here changes what a tool runs.
+ */
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+const SECRET_KEY_RE =
+	/(?:api[-_]?key|access[-_]?key|auth(?:orization)?|credential|password|private[-_]?key|secret|token)/iu;
+const ENV_KEY_RE = /^env(?:ironment)?$/iu;
+const SECRET_STRING_RE = /(https?:\/\/[^\s/@]+:)[^\s/@]+@/giu;
+const SECRET_URL_PARAM_RE =
+	/([?&](?:api[-_]?key|access[-_]?token|auth(?:orization)?|credential|password|secret|token)[^=\s]*=)[^&#\s]+/giu;
+const SECRET_ASSIGNMENT_RE =
+	/(?<![A-Z0-9_])((?:[A-Z0-9_]*(?:ACCESS|API|AUTH|CREDENTIAL|KEY|PASS(?:WORD)?|PRIVATE|SECRET|TOKEN)[A-Z0-9_]*)=)[^\s;&|]+/giu;
+const SECRET_FLAG_RE =
+	/(--?(?:[a-z0-9-]*(?:api[-_]?key|access[-_]?token|auth(?:orization)?|credential|password|secret|token)[a-z0-9-]*))(=|\s+)([^\s;&|]+)/giu;
+
+/** Scrub credentials embedded in one string: URL userinfo, query params, `KEY=value`, and `--flag value`. */
+export function redactSecretString(value: string): string {
+	return value
+		.replace(SECRET_STRING_RE, "$1[redacted]@")
+		.replace(SECRET_URL_PARAM_RE, "$1[redacted]")
+		.replace(SECRET_ASSIGNMENT_RE, "$1[redacted]")
+		.replace(SECRET_FLAG_RE, "$1$2[redacted]");
+}
+
+/** Whether an argument key names a secret outright, so its value never renders. */
+export function isSecretArgKey(key: string): boolean {
+	return SECRET_KEY_RE.test(key);
+}
+
+/** Whether an argument key names an environment block, whose every string value is a candidate secret. */
+function isEnvironmentArgKey(key: string): boolean {
+	return ENV_KEY_RE.test(key);
+}
+
+function redactEnvironmentValue(value: unknown, depth: number): unknown {
+	if (depth > 8) return "[redacted nested values]";
+	if (typeof value === "string") return "[redacted]";
+	if (Array.isArray(value)) return value.map((item) => redactEnvironmentValue(item, depth + 1));
+	if (!isPlainObject(value)) return value;
+	const out: Record<string, unknown> = {};
+	for (const [childKey, childValue] of Object.entries(value)) {
+		out[childKey] = redactEnvironmentValue(childValue, depth + 1);
+	}
+	return out;
+}
+
+/** Project tool arguments for display only; execution and receipts retain the original values. */
+export function redactToolArgs(value: unknown, key = "", depth = 0): unknown {
+	if (isSecretArgKey(key)) return "[redacted]";
+	if (isEnvironmentArgKey(key)) return redactEnvironmentValue(value, depth);
+	if (typeof value === "string") return redactSecretString(value);
+	if (depth > 8) return "[redacted nested values]";
+	if (Array.isArray(value)) return value.map((item) => redactToolArgs(item, key, depth + 1));
+	if (!isPlainObject(value)) return value;
+	const out: Record<string, unknown> = {};
+	for (const [childKey, childValue] of Object.entries(value)) {
+		out[childKey] = redactToolArgs(childValue, childKey, depth + 1);
+	}
+	return out;
+}

package/src/domains/session/context-ledger.ts

@@ -16,7 +16,7 @@
  * proportional reconciliation the footer bar already performs.
  */
 
-import type { ContextWindowSource } from "../providers/index.js";
+import type { ContextWindowSlots, ContextWindowSource } from "../providers/index.js";
 import { DEFAULT_COMPACTION_THRESHOLD } from "./compaction/auto.js";
 
 /** Distinct buckets a context window is divided into for display. */
@@ -46,6 +46,8 @@ export interface BuildContextLedgerInput {
 	contextWindow: number | null;
 	/** Which layer answered `contextWindow`; omitted before a runtime resolves. */
 	contextWindowSource?: ContextWindowSource | null;
+	/** The server-side split the probed window is a share of, when there is one. */
+	contextWindowSlots?: ContextWindowSlots | null;
 	/**
 	 * Per-segment token estimates from the prompt compiler's segment manifest.
 	 * When empty, `systemPromptTokens` is used as a single opaque system bucket.
@@ -146,6 +148,12 @@ export interface ContextLedger {
 	 * the difference decides whether autocompact fires in time.
 	 */
 	contextWindowSource: ContextWindowSource | null;
+	/**
+	 * Present when `contextWindow` is one slot's share of the server's KV
+	 * budget, so the overlay can show `196,608 (786,432 / 4 slots)` instead of
+	 * a number that looks like the whole server.
+	 */
+	contextWindowSlots: ContextWindowSlots | null;
 	/** Sum of every content category (system..pending). */
 	usedTokens: number;
 	/** Autocompact headroom held in reserve above the conversation. */
@@ -346,6 +354,7 @@ export function buildContextLedger(input: BuildContextLedgerInput): ContextLedge
 		model: input.model ?? null,
 		contextWindow: window,
 		contextWindowSource: input.contextWindowSource ?? null,
+		contextWindowSlots: input.contextWindowSlots ?? null,
 		usedTokens,
 		reserveTokens,
 		freeTokens,

package/src/domains/session/decision-board.ts

@@ -1,4 +1,5 @@
 import type { AskUserToolPolicy } from "../../tools/registry.js";
+import type { AutonomyExposure } from "../safety/autonomy.js";
 import type { DecisionLedgerEntry, DecisionRecord } from "./entries.js";
 
 export interface DecisionLedgerEntryFields {
@@ -11,6 +12,7 @@ export interface DecisionLedgerEntryFields {
 	roundCount: number;
 	summary?: string;
 	transcriptPath?: string;
+	exposure?: AutonomyExposure;
 	decisions: DecisionRecord[];
 }
 
@@ -83,6 +85,7 @@ export function finalizedInterviewEntryFields(policy: AskUserToolPolicy): Decisi
 		roundCount: policy.rounds.length,
 		...(policy.summary ? { summary: policy.summary } : {}),
 		...(policy.transcriptPath ? { transcriptPath: policy.transcriptPath } : {}),
+		exposure: policy.exposure ?? "local",
 		decisions: [...decisionsByKey.values()],
 	};
 }
@@ -172,6 +175,7 @@ export function createDecisionBoardStore(deps: DecisionBoardStoreDeps = {}): Dec
 				roundCount: interview.roundCount,
 				...(interview.summary ? { summary: interview.summary } : {}),
 				...(interview.transcriptPath ? { transcriptPath: interview.transcriptPath } : {}),
+				...(interview.exposure ? { exposure: interview.exposure } : {}),
 				decisions: interview.decisions.map((decision) => {
 					if (decision.key !== selected.key) return { ...decision };
 					const next: DecisionRecord = { ...decision, status: "superseded", revisedAt };

package/src/domains/session/entries.ts

@@ -13,6 +13,7 @@
 
 import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
 import type { ClioTurnRecord } from "../../engine/session.js";
+import { AUTONOMY_EXPOSURES, type AutonomyExposure } from "../safety/autonomy.js";
 
 export interface SessionHeader {
 	type: "session";
@@ -229,6 +230,7 @@ export interface DecisionLedgerEntry extends BaseSessionEntry {
 	roundCount: number;
 	summary?: string;
 	transcriptPath?: string;
+	exposure?: AutonomyExposure;
 	decisions: DecisionRecord[];
 }
 
@@ -643,6 +645,7 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				v.roundCount >= 0 &&
 				isOptionalString(v.summary) &&
 				isOptionalString(v.transcriptPath) &&
+				(v.exposure === undefined || isOneOf(v.exposure, AUTONOMY_EXPOSURES)) &&
 				Array.isArray(v.decisions) &&
 				v.decisions.every(isDecisionRecord)
 			);