@gajae-code/coding-agent 0.12.0 → 0.12.2

package/src/exec/bash-executor.ts

@@ -8,12 +8,125 @@ import { executeShell, type MinimizerOptions, Shell } from "@gajae-code/natives"
 import { postmortem } from "@gajae-code/utils";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { formatCrashDiagnosticNotice, writeCrashReport } from "../debug/crash-diagnostics";
-import { OutputSink } from "../session/streaming-output";
-import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
+import {
+	DEFAULT_ARTIFACT_MAX_BYTES,
+	DEFAULT_MAX_BYTES,
+	OutputSink,
+	type TerminalArtifactPublisher,
+	truncateHeadBytes,
+} from "../session/streaming-output";
+import { formatArtifactReference, resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
 import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
 
+export interface BashArtifactSaveSummary {
+	artifactId: string;
+	complete: boolean;
+	omittedBytes?: number;
+}
+
+export type BashMinimizedSaveReturn = BashArtifactSaveResult | BashArtifactSaveSummary | string | undefined;
+
+export type BashArtifactSaveResult =
+	| { status: "saved"; artifactId: string; complete: true; omittedBytes?: undefined }
+	| { status: "saved"; artifactId: string; complete: false; omittedBytes: number }
+	| { status: "unavailable" }
+	| { status: "failed"; diagnostic: string };
+
+function summarizeLegacyArtifactSave(artifactId: string, originalText: string): BashArtifactSaveResult {
+	const inputBytes = Buffer.byteLength(originalText, "utf-8");
+	if (inputBytes <= DEFAULT_ARTIFACT_MAX_BYTES) {
+		return { status: "saved", artifactId, complete: true };
+	}
+	const retainedBytes = truncateHeadBytes(originalText, DEFAULT_ARTIFACT_MAX_BYTES).bytes;
+	return {
+		status: "saved",
+		artifactId,
+		complete: false,
+		omittedBytes: inputBytes - retainedBytes,
+	};
+}
+
+function normalizeExplicitSavedArtifact(
+	artifactId: string,
+	complete: boolean,
+	omittedBytes: number | undefined,
+): BashArtifactSaveResult {
+	if (complete) {
+		return (omittedBytes ?? 0) > 0
+			? { status: "failed", diagnostic: "artifact save reported complete output with omitted bytes" }
+			: { status: "saved", artifactId, complete: true };
+	}
+	return typeof omittedBytes === "number" && omittedBytes > 0
+		? { status: "saved", artifactId, complete: false, omittedBytes }
+		: { status: "failed", diagnostic: "artifact save reported incomplete output without omitted bytes" };
+}
+
+function normalizeMinimizedSaveResult(value: BashMinimizedSaveReturn, originalText: string): BashArtifactSaveResult {
+	if (typeof value === "string") return summarizeLegacyArtifactSave(value, originalText);
+	if (!value) return { status: "unavailable" };
+	if (!("status" in value)) {
+		return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
+	}
+	if (value.status !== "saved") return value;
+	return normalizeExplicitSavedArtifact(value.artifactId, value.complete, value.omittedBytes);
+}
+
+export function normalizeMinimizedSaveResultForTests(
+	value: BashMinimizedSaveReturn,
+	originalText: string,
+): BashArtifactSaveResult {
+	return normalizeMinimizedSaveResult(value, originalText);
+}
+
+function completeRawArtifactAvailable(summary: {
+	artifactId?: string;
+	artifactTruncatedBytes?: number;
+	artifactFailureDiagnostic?: string;
+}): boolean {
+	return (
+		summary.artifactId !== undefined &&
+		(summary.artifactTruncatedBytes ?? 0) <= 0 &&
+		summary.artifactFailureDiagnostic === undefined
+	);
+}
+
+function appendModelNotice(output: string, notice: string): string {
+	const separator = output.length > 0 && !output.endsWith("\n") ? "\n" : "";
+	return `${output}${separator}${notice}\n`;
+}
+
+function minimizedSaveNotice(
+	result: BashArtifactSaveResult,
+	summary: { artifactId?: string; artifactTruncatedBytes?: number; artifactFailureDiagnostic?: string },
+): string | undefined {
+	if (result.status === "failed") return `Bash output artifact save failed: ${result.diagnostic}`;
+	if (result.status === "unavailable" && !completeRawArtifactAvailable(summary)) {
+		return "Bash output artifact unavailable: full original output could not be stored because artifact storage is unavailable.";
+	}
+	return undefined;
+}
+
+function minimizedArtifactFooter(result: Extract<BashArtifactSaveResult, { status: "saved" }>): string {
+	const reference = result.complete
+		? `artifact://${result.artifactId}`
+		: formatArtifactReference(result.artifactId, result.omittedBytes);
+	return `[raw output: ${reference}]`;
+}
+
 export interface BashExecutorOptions {
+	/**
+	 * Invoked when the native minimizer rewrote the command's output, giving
+	 * the caller a chance to persist the lossless original capture (typically
+	 * via the session's `ArtifactManager`). Complete saves preserve the
+	 * historical `[raw output: artifact://<id>]` footer; capped saves carry an
+	 * honest retained/omitted reference. A legacy string id is still accepted
+	 * for non-tool callers and is classified from the original UTF-8 byte count.
+	 */
+	onMinimizedSave?: (
+		originalText: string,
+		info: { filter: string; inputBytes: number; outputBytes: number },
+	) => Promise<BashMinimizedSaveReturn>;
 	cwd?: string;
 	timeout?: number | null;
 	onChunk?: (chunk: string) => void;
@@ -32,23 +145,18 @@ export interface BashExecutorOptions {
 	/** Artifact path/id for full output storage */
 	artifactPath?: string;
 	artifactId?: string;
+	/** Optional terminal publisher for managed artifacts without writable paths. */
+	artifactPublisher?: TerminalArtifactPublisher;
+	/** Optional Bash-specific retained tail budget in bytes. */
+	spillThreshold?: number;
+	/** Optional Bash-specific retained head budget in bytes. */
+	headBytes?: number;
 	/** Execute without retaining a native Shell in the persistent session registry. */
 	oneShot?: boolean;
 	/** Ignore user-configured shell command prefixes. Used by constrained read-only shells. */
 	ignoreShellPrefix?: boolean;
 	/** Skip sourced shell snapshots. Used by constrained read-only shells. */
 	disableShellSnapshot?: boolean;
-	/**
-	 * Invoked when the native minimizer rewrote the command's output, giving
-	 * the caller a chance to persist the lossless original capture (typically
-	 * via the session's `ArtifactManager`). The returned id is spliced into
-	 * the sink output as `artifact://<id>` so the agent can retrieve the raw
-	 * bytes. Return `undefined` to skip the footer.
-	 */
-	onMinimizedSave?: (
-		originalText: string,
-		info: { filter: string; inputBytes: number; outputBytes: number },
-	) => Promise<string | undefined>;
 }
 
 export interface BashResult {
@@ -61,6 +169,8 @@ export interface BashResult {
 	outputLines: number;
 	outputBytes: number;
 	artifactId?: string;
+	artifactTruncatedBytes?: number;
+	artifactFailureDiagnostic?: string;
 }
 
 const shellSessions = new Map<string, Shell>();
@@ -144,7 +254,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		onRawChunk: options?.onRawChunk,
 		artifactPath: options?.artifactPath,
 		artifactId: options?.artifactId,
-		headBytes: resolveOutputSinkHeadBytes(settings),
+		artifactPublisher: options?.artifactPublisher,
+		spillThreshold: options?.spillThreshold ?? DEFAULT_MAX_BYTES,
+		headBytes: options?.headBytes ?? resolveOutputSinkHeadBytes(settings),
 		maxColumns: resolveOutputMaxColumns(settings),
 		// Throttle the streaming preview callback to avoid saturating the
 		// event loop when commands produce massive output (e.g. seq 1 50M).
@@ -332,21 +444,23 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 
 		// When the native minimizer rewrote the output, swap the sink's accumulated
 		// raw stream for the minimized text, persist the original as a session
-		// artifact, and splice an `artifact://<id>` footer into the visible text so
-		// the agent can retrieve the raw bytes losslessly.
+		// artifact, and splice an artifact footer into the visible text so the agent
+		// can retrieve retained raw bytes without a false completeness claim.
 		const minimized = winner.result.minimized;
+		let minimizedSaveResult: BashArtifactSaveResult | undefined;
 		if (minimized && minimized.text !== minimized.originalText) {
 			sink.replace(minimized.text);
-			if (options?.onMinimizedSave) {
-				const artifactId = await options.onMinimizedSave(minimized.originalText, {
-					filter: minimized.filter,
-					inputBytes: minimized.inputBytes,
-					outputBytes: minimized.outputBytes,
-				});
-				if (artifactId) {
-					const sep = minimized.text.endsWith("\n") ? "" : "\n";
-					sink.push(`${sep}[raw output: artifact://${artifactId}]\n`);
-				}
+			const saved = options?.onMinimizedSave
+				? await options.onMinimizedSave(minimized.originalText, {
+						filter: minimized.filter,
+						inputBytes: minimized.inputBytes,
+						outputBytes: minimized.outputBytes,
+					})
+				: undefined;
+			minimizedSaveResult = normalizeMinimizedSaveResult(saved, minimized.originalText);
+			if (minimizedSaveResult.status === "saved") {
+				const sep = minimized.text.endsWith("\n") ? "" : "\n";
+				sink.push(`${sep}${minimizedArtifactFooter(minimizedSaveResult)}\n`);
 			}
 		}
 
@@ -366,10 +480,13 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 		}
 
 		// Normal completion
+		const summary = await sink.dump();
+		const saveNotice = minimizedSaveResult ? minimizedSaveNotice(minimizedSaveResult, summary) : undefined;
 		return {
 			exitCode: winner.result.exitCode,
 			cancelled: false,
-			...(await sink.dump()),
+			...summary,
+			...(saveNotice ? { output: appendModelNotice(summary.output, saveNotice) } : {}),
 		};
 	} catch (err) {
 		resetSession = true;

package/src/extensibility/extensions/runner.ts

@@ -179,8 +179,12 @@ export class ExtensionRunner {
 
 	#getModel: () => Model | undefined = () => undefined;
 	#isIdleFn: () => boolean = () => true;
+	#getActivePromptHandleFn: () => string | undefined = () => undefined;
 	#waitForIdleFn: () => Promise<void> = async () => {};
 	#abortFn: () => void = () => {};
+	#abortPromptAndWaitFn: NonNullable<ExtensionContextActions["abortPromptAndWait"]> = async () => {
+		throw new Error("abortPromptAndWait binding is unavailable");
+	};
 	#hasPendingMessagesFn: () => boolean = () => false;
 	#getPendingMessageCountsFn: () => { steering: number; followUp: number; nextTurn: number } = () => ({
 		steering: 0,
@@ -214,6 +218,7 @@ export class ExtensionRunner {
 	#getJobsFn: ExtensionContextActions["getJobs"] = undefined;
 	#sdkControlFn: ExtensionContextActions["sdkControl"] = undefined;
 	#setSdkPermissionProviderFn: ExtensionContextActions["setSdkPermissionProvider"] = undefined;
+	#setSdkClientBridgeFn: ExtensionContextActions["setSdkClientBridge"] = undefined;
 
 	#invokeSkillFn: ExtensionContextActions["invokeSkill"] = undefined;
 	#setPlanModeFn: ExtensionContextActions["setPlanMode"] = undefined;
@@ -297,7 +302,13 @@ export class ExtensionRunner {
 		// Context actions (required)
 		this.#getModel = contextActions.getModel;
 		this.#isIdleFn = contextActions.isIdle;
+		this.#getActivePromptHandleFn = contextActions.getActivePromptHandle ?? (() => undefined);
 		this.#abortFn = contextActions.abort;
+		this.#abortPromptAndWaitFn =
+			contextActions.abortPromptAndWait ??
+			(async () => {
+				throw new Error("abortPromptAndWait binding is unavailable");
+			});
 		this.#hasPendingMessagesFn = contextActions.hasPendingMessages;
 		this.#getPendingMessageCountsFn =
 			contextActions.getPendingMessageCounts ?? (() => ({ steering: 0, followUp: 0, nextTurn: 0 }));
@@ -331,6 +342,7 @@ export class ExtensionRunner {
 		this.#getJobsFn = contextActions.getJobs;
 		this.#sdkControlFn = contextActions.sdkControl;
 		this.#setSdkPermissionProviderFn = contextActions.setSdkPermissionProvider;
+		this.#setSdkClientBridgeFn = contextActions.setSdkClientBridge;
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -551,8 +563,10 @@ export class ExtensionRunner {
 			get model() {
 				return getModel();
 			},
+			getActivePromptHandle: () => this.#getActivePromptHandleFn(),
 			isIdle: () => this.#isIdleFn(),
 			abort: () => this.#abortFn(),
+			abortPromptAndWait: (handle, options) => this.#abortPromptAndWaitFn(handle, options),
 			hasPendingMessages: () => this.#hasPendingMessagesFn(),
 			getPendingMessageCounts: () => this.#getPendingMessageCountsFn(),
 			getTranscript: () => this.#getTranscriptFn(),
@@ -582,6 +596,7 @@ export class ExtensionRunner {
 			getJobs: () => this.#getJobsFn?.(),
 			sdkControl: (operation, input) => this.#sdkControlFn?.(operation, input),
 			setSdkPermissionProvider: provider => this.#setSdkPermissionProviderFn?.(provider),
+			setSdkClientBridge: bridge => this.#setSdkClientBridgeFn?.(bridge),
 			sdkBindings: () => [
 				...(this.#cycleModelFn ? ["cycleModel"] : []),
 				...(this.#setModelProfileFn ? ["setModelProfile"] : []),

package/src/extensibility/extensions/types.ts

@@ -8,7 +8,13 @@
  * - Interact with the user via UI primitives
  */
 
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@gajae-code/agent-core";
+import type {
+	AgentMessage,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	RunSettlementProof,
+	ThinkingLevel,
+} from "@gajae-code/agent-core";
 import type { CompactionResult } from "@gajae-code/agent-core/compaction";
 import type {
 	Api,
@@ -38,6 +44,7 @@ import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
 import type {
+	ClientBridge,
 	ClientBridgePermissionOption,
 	ClientBridgePermissionOutcome,
 	ClientBridgePermissionToolCall,
@@ -355,8 +362,12 @@ export interface ExtensionContext {
 	model: Model | undefined;
 	/** Whether the agent is idle (not streaming) */
 	isIdle(): boolean;
+	/** Stable resource ownership identifier for the active prompt run. */
+	getActivePromptHandle(): string | undefined;
 	/** Abort the current agent operation */
 	abort(): void;
+	/** Abort and prove whether resources for a specific prompt settled. */
+	abortPromptAndWait?(handle: string, options: { graceMs: number }): Promise<RunSettlementProof>;
 	/** Whether there are queued messages waiting */
 	hasPendingMessages(): boolean;
 	/** Typed pending-message counts per queue (steering, follow-up, next-turn). */
@@ -416,6 +427,8 @@ export interface ExtensionContext {
 			  ) => Promise<ClientBridgePermissionOutcome>)
 			| undefined,
 	): void;
+	/** Install a client bridge backed by a live SDK reverse provider lease. */
+	setSdkClientBridge?(bridge: ClientBridge | undefined): void;
 	/** Names of session SDK seams actually installed by the active runtime. */
 	sdkBindings?(): readonly string[];
 
@@ -1436,7 +1449,10 @@ export interface ExtensionActions {
 export interface ExtensionContextActions {
 	getModel: () => Model | undefined;
 	isIdle: () => boolean;
+	/** Stable resource ownership identifier for the active prompt run. */
+	getActivePromptHandle?: () => string | undefined;
 	abort: () => void;
+	abortPromptAndWait?: (handle: string, options: { graceMs: number }) => Promise<RunSettlementProof>;
 	hasPendingMessages: () => boolean;
 	/** Typed pending-message counts per queue; optional for embedders without a counted queue. */
 	getPendingMessageCounts?: () => { steering: number; followUp: number; nextTurn: number };
@@ -1484,6 +1500,7 @@ export interface ExtensionContextActions {
 			  ) => Promise<ClientBridgePermissionOutcome>)
 			| undefined,
 	) => void;
+	setSdkClientBridge?: (bridge: ClientBridge | undefined) => void;
 	sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
 	invokeSkill?: (
 		name: string,

package/src/extensibility/gjc-plugins/constrained-hooks.ts

@@ -1,8 +1,8 @@
 import { logger } from "@gajae-code/utils";
-
+import { bundleIdentity } from "./lifecycle-reconciliation";
 import { loadEffectiveGjcPluginRegistry } from "./registry";
 import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
-import { GjcPluginLoadError, type GjcPluginRegistryEntry } from "./types";
+import { GjcPluginLoadError, type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
 
 /**
  * Constrained plugin-hook loader.
@@ -37,6 +37,7 @@ const DENIED_API_METHODS = [
 
 interface DeclaredHook {
 	plugin: string;
+	scope: GjcPluginScope;
 	event: string;
 	target?: string;
 	phase?: "before" | "after";
@@ -52,6 +53,7 @@ function collectDeclaredHooks(entries: readonly GjcPluginRegistryEntry[]): Decla
 			if (disabled.has(h.extensionId)) continue;
 			out.push({
 				plugin: entry.name,
+				scope: entry.scope,
 				event: h.event,
 				target: h.target,
 				phase: h.phase,
@@ -88,6 +90,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}:${declared.target ?? ""}`,
 				code: "invalid_hook",
@@ -99,6 +102,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code: "invalid_hook",
@@ -113,6 +117,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code,
@@ -125,6 +130,7 @@ async function loadOneHook(
 		return {
 			hook: null,
 			quarantine: {
+				identity: bundleIdentity(declared.scope, declared.plugin),
 				plugin: declared.plugin,
 				surfaceId: `hook:${declared.event}`,
 				code: "runtime_mismatch",

package/src/extensibility/gjc-plugins/index.ts

@@ -2,14 +2,31 @@ export * from "./activation";
 export * from "./compiler";
 export * from "./constrained-hooks";
 export * from "./injection";
-export * from "./installer";
+/**
+ * Public barrel. Mutation primitives are deliberately NOT re-exported here:
+ * `lifecycle.ts` is the sole policy and persistence writer, so the installer
+ * transaction and the registry writers stay reachable only through their own
+ * modules. Re-exporting them would let a caller commit a replacement and
+ * bypass the create-only rule.
+ */
+export { isGjcPluginBundleSource, isGjcPluginSourceShape } from "./installer";
+export * from "./lifecycle";
+export * from "./lifecycle-reconciliation";
 export * from "./loader";
 export * from "./mcp-policy";
 export * from "./observability";
 export * from "./paths";
 export * from "./prompt-appendix";
-export * from "./registry";
+export {
+	loadEffectiveGjcPluginRegistry,
+	readRegistry,
+	registryEntryFingerprint,
+	registryPathForScope,
+	registryRootForScope,
+	sortRegistryEntries,
+} from "./registry";
 export * from "./runtime-adapters";
+export * from "./runtime-quarantine";
 export * from "./schema";
 export * from "./session-validation";
 export * from "./state";