@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/utils/herdr-pane.ts

@@ -0,0 +1,345 @@
+/**
+ * Herdr agent lifecycle reporter.
+ *
+ * When gjc runs inside a Herdr pane (`HERDR_ENV=1`), report semantic agent
+ * state through Herdr's documented custom-integration API so the pane is
+ * recognized as the "gjc" agent in Herdr's sidebar and workspace rollups:
+ *
+ *   - `idle`    — waiting at the input prompt (also reported at startup)
+ *   - `working` — agent turn in progress
+ *   - `blocked` — waiting on a user decision (ask tool)
+ *
+ * The session title is reported through the same API as display-only pane
+ * metadata, so a pane shows what it is working on instead of a bare agent
+ * label. Herdr renders that title on the pane border and exposes it to the
+ * sidebar as the `pane` token.
+ *
+ * Reporting is strictly best-effort and never blocks or fails a turn. Outside
+ * a Herdr pane every entry point is a no-op. Herdr also clears the authority
+ * when the pane's foreground process exits, so a hard kill still recovers.
+ *
+ * Original implementation contributed by @ox8884 (#4318).
+ */
+import { logger } from "@gajae-code/utils";
+
+const HERDR_ENV = "HERDR_ENV";
+const HERDR_PANE_ID_ENV = "HERDR_PANE_ID";
+const HERDR_BIN_PATH_ENV = "HERDR_BIN_PATH";
+const HERDR_COMMAND = "herdr";
+const AGENT_LABEL = "gjc";
+const SOURCE = "custom:gjc";
+/** A report is a fire-and-forget status ping; a hung herdr CLI must never accumulate. */
+const HERDR_REPORT_TIMEOUT_MS = 1500;
+/** Release runs on the shutdown path, so it is bounded even tighter. */
+const HERDR_RELEASE_TIMEOUT_MS = 1000;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/** Herdr truncates to the pane width anyway; this only bounds the argv. */
+const MAX_PANE_TITLE_CHARS = 120;
+
+/**
+ * Metadata reports carry their own per-source sequence in Herdr, independent of
+ * the lifecycle-state sequence, so title updates need a counter of their own.
+ * Module scope because the title is a property of the process, not of one
+ * reporter instance: `setSessionTerminalTitle` is called from controllers that
+ * never see the reporter.
+ */
+let metadataSeq = 0;
+
+function nextMetadataSeq(): number {
+	metadataSeq += 1;
+	return metadataSeq;
+}
+
+export type HerdrAgentState = "idle" | "working" | "blocked";
+
+export interface HerdrPaneEnvironment {
+	paneId: string;
+	binPath: string;
+}
+
+export interface HerdrReportProcess {
+	exited: Promise<number>;
+	kill(): void;
+	unref(): void;
+}
+
+export interface HerdrReporterOptions {
+	env?: NodeJS.ProcessEnv;
+	which?: (command: string) => string | null;
+	spawn?: (
+		command: string[],
+		options: { env: NodeJS.ProcessEnv; stdin: "ignore"; stdout: "ignore"; stderr: "ignore" },
+	) => HerdrReportProcess;
+}
+
+/** Session event shape consumed by the reporter. Narrow on purpose: the state
+ * machine is driven only by lifecycle transitions, never by message content. */
+export interface HerdrSessionEvent {
+	type: string;
+	toolName?: string;
+}
+
+export interface HerdrReporter {
+	/** Report a new agent state. Deduplicated against the last reported state. */
+	report(state: HerdrAgentState): void;
+	/** Release this pane's lifecycle authority and stop listening. Idempotent. */
+	release(): void;
+	/** Current reported state, for tests and diagnostics. */
+	readonly state: HerdrAgentState | null;
+}
+
+function defaultSpawn(
+	command: string[],
+	options: { env: NodeJS.ProcessEnv; stdin: "ignore"; stdout: "ignore"; stderr: "ignore" },
+): HerdrReportProcess {
+	return Bun.spawn(command, options);
+}
+
+/**
+ * Resolve the pane environment. Returns null unless gjc is demonstrably inside
+ * a Herdr pane AND a herdr binary is resolvable.
+ *
+ * `HERDR_BIN_PATH` is honored first because Herdr sets it for its own panes;
+ * otherwise the binary is resolved from PATH. No home-directory guessing: an
+ * unverified path scavenged from an install layout is a command this process
+ * would execute, and PATH/`HERDR_BIN_PATH` are the trust boundary Herdr itself
+ * documents.
+ */
+export function resolveHerdrPaneEnvironment(options: HerdrReporterOptions = {}): HerdrPaneEnvironment | null {
+	const env = options.env ?? process.env;
+	if (env[HERDR_ENV]?.trim() !== "1") return null;
+
+	const paneId = env[HERDR_PANE_ID_ENV]?.trim();
+	// A pane id is forwarded verbatim as an argv element; reject anything that is
+	// not an opaque identifier rather than trusting the surrounding environment.
+	// The leading character must be alphanumeric so a pane id can never be parsed
+	// by the herdr CLI as an option.
+	if (!paneId || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(paneId)) return null;
+
+	const configured = env[HERDR_BIN_PATH_ENV]?.trim();
+	if (configured) return { paneId, binPath: configured };
+
+	const which = options.which ?? Bun.which;
+	try {
+		const resolved = which(HERDR_COMMAND);
+		return resolved ? { paneId, binPath: resolved } : null;
+	} catch (error) {
+		logger.debug("herdr binary lookup failed", { error: String(error) });
+		return null;
+	}
+}
+
+/** Build the argv for a state report. Exported for tests. */
+export function buildHerdrReportArgs(paneId: string, state: HerdrAgentState, seq: number): string[] {
+	return [
+		"pane",
+		"report-agent",
+		paneId,
+		"--source",
+		SOURCE,
+		"--agent",
+		AGENT_LABEL,
+		"--state",
+		state,
+		"--seq",
+		String(seq),
+	];
+}
+
+/** Build the argv for an authority release. Exported for tests. */
+export function buildHerdrReleaseArgs(paneId: string, seq: number): string[] {
+	return ["pane", "release-agent", paneId, "--source", SOURCE, "--agent", AGENT_LABEL, "--seq", String(seq)];
+}
+
+/**
+ * Collapse a session name into a single-line pane title. Control characters are
+ * removed rather than escaped: the value reaches a terminal surface, and a
+ * model-generated session name must never be able to inject escapes.
+ */
+export function sanitizeHerdrPaneTitle(title: string | undefined): string | undefined {
+	if (!title) return undefined;
+	const sanitized = title.replace(CONTROL_CHARS, " ").replace(/\s+/g, " ").trim();
+	if (!sanitized) return undefined;
+	if (sanitized.length <= MAX_PANE_TITLE_CHARS) return sanitized;
+	// Truncate by UTF-16 code units (the Herdr argv is a string), then step back
+	// if the cut lands on the high surrogate of a pair so the title never ends
+	// with a lone surrogate.
+	let bound = MAX_PANE_TITLE_CHARS;
+	const last = sanitized.charCodeAt(bound - 1);
+	if (last >= 0xd800 && last <= 0xdbff) bound -= 1;
+	return sanitized.slice(0, bound).trimEnd();
+}
+
+/** Build the argv for a pane title report. Exported for tests. */
+export function buildHerdrTitleArgs(paneId: string, title: string, seq: number): string[] {
+	return [
+		"pane",
+		"report-metadata",
+		paneId,
+		"--source",
+		SOURCE,
+		"--agent",
+		AGENT_LABEL,
+		"--title",
+		title,
+		"--seq",
+		String(seq),
+	];
+}
+
+/** Build the argv that retracts a previously reported pane title. Exported for tests. */
+export function buildHerdrClearTitleArgs(paneId: string, seq: number): string[] {
+	return ["pane", "report-metadata", paneId, "--source", SOURCE, "--clear-title", "--seq", String(seq)];
+}
+
+/**
+ * Spawn a detached, timeout-bounded herdr CLI invocation. Every failure mode is
+ * swallowed: a status ping must never surface in a session.
+ */
+function runHerdrCommand(binPath: string, args: string[], timeoutMs: number, options: HerdrReporterOptions): void {
+	const env = options.env ?? process.env;
+	const spawn = options.spawn ?? defaultSpawn;
+
+	let proc: HerdrReportProcess;
+	try {
+		proc = spawn([binPath, ...args], {
+			env,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+	} catch (error) {
+		// Missing/unexecutable binary: reporting is best-effort, never fatal.
+		logger.debug("herdr report failed to start", { error: String(error) });
+		return;
+	}
+	proc.unref();
+	const timer = setTimeout(() => {
+		try {
+			proc.kill();
+		} catch {}
+	}, timeoutMs);
+	timer.unref?.();
+	// Bun.spawn surfaces spawn failure through `exited` rejection, so this
+	// handler is what keeps an ENOENT from becoming an unhandled rejection.
+	void proc.exited
+		.then(exitCode => {
+			clearTimeout(timer);
+			if (exitCode !== 0) logger.debug("herdr report exited non-zero", { exitCode });
+		})
+		.catch(error => {
+			clearTimeout(timer);
+			logger.debug("herdr report failed", { error: String(error) });
+		});
+}
+
+/**
+ * Report the current session title for this pane. No-op outside a Herdr pane or
+ * when the session has no usable name, so a pane keeps the last real title
+ * instead of flickering to a placeholder during startup or a rename.
+ */
+export function syncHerdrPaneTitle(sessionName: string | undefined, options: HerdrReporterOptions = {}): void {
+	const title = sanitizeHerdrPaneTitle(sessionName);
+	if (!title) return;
+
+	const paneEnv = resolveHerdrPaneEnvironment(options);
+	if (!paneEnv) return;
+
+	runHerdrCommand(
+		paneEnv.binPath,
+		buildHerdrTitleArgs(paneEnv.paneId, title, nextMetadataSeq()),
+		HERDR_REPORT_TIMEOUT_MS,
+		options,
+	);
+}
+
+/**
+ * Create a reporter bound to a pane. `subscribe` supplies the session event
+ * stream and is parameterized so the state machine is testable without a live
+ * session.
+ */
+export function createHerdrReporter(
+	paneEnv: HerdrPaneEnvironment,
+	subscribe: (listener: (event: HerdrSessionEvent) => void) => () => void,
+	options: HerdrReporterOptions = {},
+): HerdrReporter {
+	let seq = 0;
+	let currentState: HerdrAgentState | null = null;
+	let released = false;
+	/** Nesting depth of blocking ask calls; a nested ask must not unblock early. */
+	let askDepth = 0;
+
+	const run = (args: string[], timeoutMs: number): void => {
+		runHerdrCommand(paneEnv.binPath, args, timeoutMs, options);
+	};
+
+	const report = (state: HerdrAgentState): void => {
+		if (released || state === currentState) return;
+		currentState = state;
+		seq += 1;
+		run(buildHerdrReportArgs(paneEnv.paneId, state, seq), HERDR_REPORT_TIMEOUT_MS);
+	};
+
+	let unsubscribe: (() => void) | null = subscribe(event => {
+		switch (event.type) {
+			case "agent_start":
+				askDepth = 0;
+				report("working");
+				break;
+			case "agent_end":
+				askDepth = 0;
+				report("idle");
+				break;
+			case "tool_execution_start":
+				if (event.toolName === "ask") {
+					askDepth += 1;
+					report("blocked");
+				}
+				break;
+			case "tool_execution_end":
+				if (event.toolName === "ask" && askDepth > 0) {
+					askDepth -= 1;
+					if (askDepth === 0) report("working");
+				}
+				break;
+		}
+	});
+
+	// A freshly started agent is idle at the prompt.
+	report("idle");
+
+	return {
+		report,
+		release() {
+			if (released) return;
+			released = true;
+			unsubscribe?.();
+			unsubscribe = null;
+			seq += 1;
+			run(buildHerdrReleaseArgs(paneEnv.paneId, seq), HERDR_RELEASE_TIMEOUT_MS);
+			// The pane outlives gjc, so a session title left behind would label a
+			// plain shell with the work of a session that already ended.
+			run(buildHerdrClearTitleArgs(paneEnv.paneId, nextMetadataSeq()), HERDR_RELEASE_TIMEOUT_MS);
+		},
+		get state() {
+			return currentState;
+		},
+	};
+}
+
+/**
+ * Install the Herdr reporter for a running session. No-op outside a Herdr pane.
+ * Returns the reporter so callers can release it deterministically, or null.
+ */
+export function installHerdrReporter(
+	subscribe: (listener: (event: HerdrSessionEvent) => void) => () => void,
+	options: HerdrReporterOptions = {},
+): HerdrReporter | null {
+	const paneEnv = resolveHerdrPaneEnvironment(options);
+	if (!paneEnv) return null;
+
+	const reporter = createHerdrReporter(paneEnv, subscribe, options);
+	// `exit` handlers must be synchronous; release() only spawns and returns.
+	process.once("exit", reporter.release);
+	return reporter;
+}

package/src/utils/title-generator.ts

@@ -10,6 +10,7 @@ import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
 import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "text" };
 import { syncCmuxWorkspaceTitle } from "./cmux-workspace";
+import { syncHerdrPaneTitle } from "./herdr-pane";
 
 const TITLE_SYSTEM_PROMPT = prompt.render(titleSystemPrompt);
 
@@ -220,6 +221,7 @@ export function setTerminalTitle(title: string): void {
 export function setSessionTerminalTitle(sessionName: string | undefined, cwd?: string): void {
 	setTerminalTitle(formatSessionTerminalTitle(sessionName, cwd));
 	void syncCmuxWorkspaceTitle(sessionName);
+	syncHerdrPaneTitle(sessionName);
 }
 
 /**

package/src/web/scrapers/index.ts

@@ -161,13 +161,15 @@ export {
 	handleYouTube,
 };
 
-export const specialHandlers: SpecialHandler[] = [
+export const specialHandlers: SpecialHandler[] = [];
+
+specialHandlers.push(
 	// Git hosting
 	handleGitHubGist,
 	handleGitHub,
 	handleGitLab,
 	// Video/Media
-	handleYouTube,
+	(url, timeout, signal) => handleYouTube(url, timeout, signal),
 	handleVimeo,
 	handleSpotify,
 	handleDiscogs,
@@ -203,7 +205,7 @@ export const specialHandlers: SpecialHandler[] = [
 	handleBrew,
 	handlePyPI,
 	handleCratesIo,
-	handleDockerHub,
+	(url, timeout, signal) => handleDockerHub(url, timeout, signal),
 	handleFdroid,
 	handleFlathub,
 	handleGoPkg,
@@ -249,4 +251,4 @@ export const specialHandlers: SpecialHandler[] = [
 	handleSpdx,
 	handleWikidata,
 	handleWikipedia,
-];
+);

package/dist/types/cli/malloc-env-guard.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/defaults/gjc-defaults.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/memory-backend/lazy-loading.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/boot-ordering.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/lazy-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/network-prewarm-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime/workspace-tree-service.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/config.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/http.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/manager-pool.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/pool-key.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/runtime-mcp/pool.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/sdk/bus/lifecycle-control-runtime.d.ts

@@ -1,117 +0,0 @@
-import { type OwnerIsolationProbe } from "../../gjc-runtime/tmux-owner-isolation";
-import { type GjcTmuxSessionStatus } from "../../gjc-runtime/tmux-sessions";
-import type { ResumeCandidate, SessionCreateFrame, SessionLifecycleRequest, SessionLifecycleResponse } from "./index";
-import { type AuditEvent, type CreateEffectResult, type LedgerStore, type LifecycleOutcome, type OrchestratorDeps, type ResumeEffectResult } from "./lifecycle-orchestrator";
-/** Minimal view of the native control server this runtime depends on. */
-export interface ControlServerLike {
-    onLifecycleRequest(cb: (err: Error | null, req: {
-        kind: string;
-        requestId: string;
-        payloadJson: string;
-    }) => void): void;
-    respond(responseJson: string): void;
-}
-/**
- * A startable control server (the native NotificationControlServer, or a fake in
- * tests). Extends {@link ControlServerLike} with the start/stop lifecycle the
- * daemon owns.
- */
-export interface LifecycleControlServer extends ControlServerLike {
-    start(): Promise<unknown>;
-    stop(): void;
-}
-/** Factory the daemon uses to construct a control server bound to its ownership. */
-export type LifecycleControlServerFactory = (input: {
-    token: string;
-    ownerId: string;
-    agentDir: string;
-}) => LifecycleControlServer;
-export declare function fileLedgerStore(idempotencyFile: string): LedgerStore;
-/** Append-only JSONL audit sink (0600). Never receives tokens or raw prompts. */
-export declare function fileAudit(auditPath: string): (e: AuditEvent) => void;
-/** Simple per-chat sliding-window create rate limiter. */
-export declare function createRateLimiter(maxPerWindow: number, windowMs: number): (chatId: string, nowMs: number) => boolean;
-/** Build the `gjc` argv for a create target (existing path / worktree / dir).
- *
- *  The launched session id is carried via `GJC_SESSION_ID` in the child env (see
- *  {@link daemonSpawnCreate}); the root `gjc` launcher has no `--session-id`
- *  flag, so it must never appear in argv. Only flags the launch parser actually
- *  supports are emitted (`--worktree <branch>` for worktree targets,
- *  `--mpreset <profile>` for model presets). */
-export declare function buildCreateArgv(frame: SessionCreateFrame, _ids: {
-    intendedSessionId: string;
-    startupPromptRef?: string;
-}): {
-    cwd: string;
-    args: string[];
-};
-/** Real daemon-safe tmux launcher: canonical owner-isolation plan + GJC tags. */
-export declare function daemonSpawnCreate(env?: NodeJS.ProcessEnv, opts?: {
-    ownerIsolationProbe?: OwnerIsolationProbe;
-    platform?: NodeJS.Platform;
-    processIncarnation?: (pid: number) => string | undefined;
-}): (frame: SessionCreateFrame, ids: {
-    lifecycleRequestId: string;
-    intendedSessionId: string;
-    startupPromptRef?: string;
-}) => Promise<CreateEffectResult>;
-/** Real force-close effect (GJC-managed only, id-matched). */
-export declare function daemonCloseSession(env?: NodeJS.ProcessEnv, deps?: {
-    forceClose?: (name: string, env: NodeJS.ProcessEnv, expectedSessionId?: string, sessionStateFile?: string) => Promise<void>;
-    findSession?: (name: string, env: NodeJS.ProcessEnv) => GjcTmuxSessionStatus | undefined;
-}): (target: {
-    sessionId: string;
-    tmuxSession?: string;
-    sessionStateFile?: string;
-}) => Promise<{
-    processGone: boolean;
-}>;
-/** Real resume effect: reattach if a live GJC session matches; else resolve the
- *  prefix against saved history and fail closed (`ambiguous`/`notFound`) before
- *  cold-restarting exactly one resolved session via the daemon-safe launcher. */
-export declare function daemonResumeSession(env?: NodeJS.ProcessEnv, opts?: {
-    agentDir?: string;
-    /** Explicit managed root for isolated tests. */
-    sessionsRoot?: string;
-    listSessions?: (env: NodeJS.ProcessEnv) => GjcTmuxSessionStatus[];
-    ownerIsolationProbe?: OwnerIsolationProbe;
-    platform?: NodeJS.Platform;
-    processIncarnation?: (pid: number) => string | undefined;
-}): (target: {
-    sessionIdOrPrefix: string;
-    path?: string;
-}) => Promise<ResumeEffectResult | {
-    ambiguous: ResumeCandidate[];
-} | {
-    notFound: true;
-}>;
-/** Translate an orchestrator outcome into a wire response frame. */
-export declare function outcomeToResponse(frame: SessionLifecycleRequest, outcome: LifecycleOutcome): SessionLifecycleResponse;
-/**
- * Wire a control server's lifecycle requests through the orchestrator.
- *
- * Handlers run on a single serial queue (a promise chain): the daemon owns the
- * one control endpoint, so serializing here makes each request's ledger
- * read -> classify -> write atomic with respect to every other request. Two
- * identical updates that arrive nearly simultaneously can no longer both
- * classify as `new` and both spawn — the second sees the first's persisted
- * `in_progress`/`success` entry and re-acks instead.
- */
-export declare function attachLifecycleControl(server: ControlServerLike, deps: OrchestratorDeps): void;
-/** Assemble real orchestrator deps for the daemon (ledger/audit under agentDir). */
-export declare function buildOrchestratorDeps(input: {
-    pairedChatId: string;
-    agentNotificationsDir: string;
-    /** Required in-memory, 32-byte audit-v2 redaction key. */
-    auditRedactionKey: Uint8Array;
-    /** Root of saved session histories (`<agentDir>/sessions`), for resume resolution. */
-    sessionsRoot?: string;
-    /** Agent directory used for readonly managed-session resume resolution. */
-    agentDir?: string;
-    env?: NodeJS.ProcessEnv;
-}): OrchestratorDeps;
-/**
- * Default production factory: a real native NotificationControlServer bound to
- * the daemon's control token, owner id, and agent dir.
- */
-export declare const createNativeControlServer: LifecycleControlServerFactory;