@a5c-ai/babysitter-sdk 5.0.0 → 5.0.1-staging.04a3db697

package/dist/cli/commands/hooks/run.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * hook:run CLI command.
+ *
+ * Dispatches hook handling to the appropriate harness adapter.
+ * Each harness (e.g. "claude-code") implements its own stop and
+ * session-start handlers via the HarnessAdapter interface.
+ *
+ * The "user-prompt-submit" hook type is harness-agnostic: it reads the
+ * Claude Code UserPromptSubmit JSON payload from stdin, applies density-filter
+ * compression if the prompt exceeds the configured token threshold, and writes
+ * the (possibly compressed) payload to stdout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookRun = handleHookRun;
+const harness_1 = require("../../../harness");
+const config_loader_1 = require("../../../compression/config-loader");
+const density_filter_1 = require("../../../compression/density-filter");
+const runLogger_1 = require("../../../logging/runLogger");
+// ---------------------------------------------------------------------------
+// Stdin reader
+// ---------------------------------------------------------------------------
+async function readStdin() {
+    const chunks = [];
+    return new Promise((resolve, reject) => {
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+async function handleUserPromptSubmit() {
+    let raw;
+    try {
+        raw = await readStdin();
+    }
+    catch {
+        return 0;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        // Not valid JSON — pass through unchanged
+        process.stdout.write(raw);
+        return 0;
+    }
+    // Apply compression only if enabled; if disabled, falls through and outputs original payload
+    const config = (0, config_loader_1.loadCompressionConfig)(process.cwd());
+    const layer = config.layers.userPromptHook;
+    if (config.enabled && layer.enabled) {
+        const prompt = payload.prompt;
+        if (typeof prompt === "string") {
+            const tokenCount = (0, density_filter_1.estimateTokens)(prompt);
+            if (tokenCount > layer.threshold) {
+                payload.prompt = (0, density_filter_1.densityFilterText)(prompt, 1 - layer.keepRatio);
+            }
+        }
+    }
+    process.stdout.write(JSON.stringify(payload));
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// pre-tool-use handler (harness-agnostic, self-contained)
+//
+// Reads the Claude Code PreToolUse JSON payload from stdin, checks if the
+// Bash command is a simple compressible one (git, ls, grep, diff, cat, …),
+// and rewrites it to `babysitter compress-output <cmd>` so command output is
+// compressed before it enters Claude's context window.
+//
+// Replaces the external rtk-rewrite.sh hook with a self-contained babysitter
+// implementation.
+// ---------------------------------------------------------------------------
+const COMPRESSIBLE_BINS = new Set([
+    "git", "ls", "dir", "grep", "rg", "ag", "diff", "delta",
+    "cat", "head", "tail", "less", "more",
+]);
+/** Returns true if the command is a plain invocation with no shell operators. */
+function isSimpleCommand(cmd) {
+    // Skip rewrites for commands that contain pipes, redirects, subshells, etc.
+    return !/[|;&<>`]|\$\(/.test(cmd);
+}
+async function handlePreToolUse() {
+    let raw;
+    try {
+        raw = await readStdin();
+    }
+    catch {
+        return 0;
+    }
+    // Check feature flag before doing anything
+    const config = (0, config_loader_1.loadCompressionConfig)(process.cwd());
+    if (!config.enabled || !config.layers.commandOutputHook.enabled) {
+        return 0;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        // Not JSON — pass through
+        return 0;
+    }
+    const toolInput = payload.tool_input;
+    const command = typeof toolInput?.command === "string" ? toolInput.command.trim() : "";
+    if (!command)
+        return 0;
+    const firstToken = command.split(/\s+/)[0]?.toLowerCase() ?? "";
+    if (!COMPRESSIBLE_BINS.has(firstToken))
+        return 0;
+    if (!isSimpleCommand(command))
+        return 0;
+    // Respect excludeCommands from config
+    const excluded = config.layers.commandOutputHook.excludeCommands;
+    if (excluded.some(exc => firstToken === exc.toLowerCase()))
+        return 0;
+    // Rewrite: prepend `babysitter compress-output`
+    const rewritten = `babysitter compress-output ${command}`;
+    const updatedInput = { ...toolInput, command: rewritten };
+    const response = {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: "babysitter output compression",
+            updatedInput,
+        },
+    };
+    process.stdout.write(JSON.stringify(response) + "\n");
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Main dispatcher
+// ---------------------------------------------------------------------------
+/** Fire-and-forget log to the structured run log facility. */
+function logHookEvent(hookType, message, context) {
+    void (0, runLogger_1.appendRunLog)({
+        timestamp: new Date().toISOString(),
+        level: "info",
+        type: "hook",
+        label: `hook:${hookType}`,
+        message,
+        source: "hook:run",
+        context,
+    }).catch(() => {
+        // Never let logging break hook execution.
+    });
+}
+async function handleHookRun(args) {
+    const { hookType, harness, json } = args;
+    if (!hookType) {
+        const error = {
+            error: "MISSING_HOOK_TYPE",
+            message: "--hook-type is required for hook:run",
+        };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write("Error: --hook-type is required for hook:run\n");
+        }
+        return 1;
+    }
+    logHookEvent(hookType, "Hook invoked", { harness });
+    // harness-agnostic hook types — handle before adapter lookup
+    if (hookType === "user-prompt-submit") {
+        const code = await handleUserPromptSubmit();
+        logHookEvent(hookType, `Hook completed with code=${code}`);
+        return code;
+    }
+    if (hookType === "pre-tool-use") {
+        const code = await handlePreToolUse();
+        logHookEvent(hookType, `Hook completed with code=${code}`);
+        return code;
+    }
+    const adapter = (0, harness_1.getAdapterByName)(harness);
+    if (!adapter) {
+        const supported = (0, harness_1.listSupportedHarnesses)();
+        const error = {
+            error: "UNSUPPORTED_HARNESS",
+            message: `Unsupported harness: "${harness}". Supported: ${supported.join(", ")}`,
+        };
+        logHookEvent(hookType, `Unsupported harness: ${harness}`, { error: error.error });
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write(`Error: ${error.message}\n`);
+        }
+        return 1;
+    }
+    if (adapter.supportsHookType && !adapter.supportsHookType(hookType)) {
+        const message = adapter.getUnsupportedHookMessage
+            ? adapter.getUnsupportedHookMessage(hookType)
+            : `Harness "${harness}" does not support hook type "${hookType}".`;
+        const error = {
+            error: "UNSUPPORTED_HOOK_TYPE",
+            message,
+        };
+        logHookEvent(hookType, message, { error: error.error });
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write(`Error: ${message}\n`);
+        }
+        return 1;
+    }
+    let exitCode;
+    switch (hookType) {
+        case "stop":
+        case "session-end":
+            exitCode = await adapter.handleStopHook(args);
+            break;
+        case "session-start":
+            exitCode = await adapter.handleSessionStartHook(args);
+            break;
+        default: {
+            const error = {
+                error: "UNKNOWN_HOOK_TYPE",
+                message: `Unknown hook type: ${hookType}. Supported: stop, session-end, session-start, user-prompt-submit, pre-tool-use`,
+            };
+            logHookEvent(hookType, error.message, { error: error.error });
+            if (json) {
+                process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+            }
+            else {
+                process.stderr.write(`Error: Unknown hook type: ${hookType}. Supported: stop, session-end, session-start, user-prompt-submit, pre-tool-use\n`);
+            }
+            return 1;
+        }
+    }
+    logHookEvent(hookType, `Hook completed with code=${exitCode}`, { harness });
+    return exitCode;
+}

package/dist/cli/commands/instructions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI handlers for `instructions:*` commands.
+ *
+ * Each subcommand resolves a PromptContext for the given harness,
+ * calls the appropriate composer, and outputs the result.
+ *
+ * @module cli/commands/instructions
+ */
+export interface InstructionsCommandArgs {
+    subcommand: "babysit-skill" | "process-create" | "orchestrate" | "breakpoint-handling";
+    harness?: string;
+    interactive: boolean | undefined;
+    json: boolean;
+    showStrata?: boolean;
+}
+/**
+ * Route and handle an `instructions:*` subcommand.
+ */
+export declare function handleInstructionsCommand(args: InstructionsCommandArgs): Promise<number>;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/cli/commands/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoCH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,eAAe,GAAG,gBAAgB,GAAG,aAAa,GAAG,qBAAqB,CAAC;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA4MD;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAwGjB"}

package/dist/cli/commands/instructions.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * CLI handlers for `instructions:*` commands.
+ *
+ * Each subcommand resolves a PromptContext for the given harness,
+ * calls the appropriate composer, and outputs the result.
+ *
+ * @module cli/commands/instructions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleInstructionsCommand = handleInstructionsCommand;
+const node_fs_1 = require("node:fs");
+const prompts_1 = require("../../prompts");
+const active_1 = require("../../processLibrary/active");
+const registry_1 = require("../../harness/registry");
+const discovery_1 = require("../../harness/discovery");
+const parse_1 = require("../../session/parse");
+const contextShared_1 = require("../../prompts/contextShared");
+const detectExistingRun_1 = require("./detectExistingRun");
+const COMPOSERS = {
+    "babysit-skill": {
+        fn: prompts_1.composeBabysitSkillPrompt,
+        promptType: "babysit-skill",
+        partsIncluded: [
+            "non-negotiables", "dependencies", "interview", "user-profile",
+            "process-creation", "intent-fidelity-checks", "run-overlap-detection", "run-creation",
+            "iteration", "effects", "breakpoint-handling", "results-posting",
+            "loop-control", "completion-proof", "task-kinds", "task-examples",
+            "quick-reference", "recovery", "process-guidelines", "critical-rules",
+            "see-also",
+            "project-instructions",
+        ],
+        strataParts: [
+            "renderNonNegotiables", "renderDependencies", "renderInterview", "renderUserProfile",
+            "renderProcessCreation", "renderIntentFidelityChecks", "renderRunOverlapDetection",
+            "renderRunCreation", "renderIteration", "renderEffects", "renderBreakpointHandling",
+            "renderResultsPosting", "renderLoopControl", "renderCompletionProof",
+            "renderTaskKinds", "renderTaskExamples", "renderQuickReference", "renderRecovery",
+            "renderProcessGuidelines", "renderCriticalRules", "renderSeeAlso",
+            "renderProjectInstructions",
+        ],
+    },
+    "process-create": {
+        fn: prompts_1.composeProcessCreatePrompt,
+        promptType: "process-create",
+        partsIncluded: [
+            "interview", "user-profile", "process-creation",
+            "intent-fidelity-checks", "process-guidelines",
+            "parallel-phase-detection", "task-kinds", "task-examples",
+            "project-instructions",
+        ],
+        strataParts: [
+            "renderInterview", "renderUserProfile", "renderProcessCreation",
+            "renderIntentFidelityChecks", "renderProcessGuidelines",
+            "renderParallelPhaseDetection", "renderTaskKinds", "renderTaskExamples",
+            "renderProjectInstructions",
+        ],
+    },
+    "orchestrate": {
+        fn: prompts_1.composeOrchestrationPrompt,
+        promptType: "orchestrate",
+        partsIncluded: [
+            "run-overlap-detection", "run-creation", "iteration", "effects", "breakpoint-handling",
+            "results-posting", "loop-control", "completion-proof",
+            "quick-reference", "recovery", "critical-rules",
+        ],
+        strataParts: [
+            "renderRunOverlapDetection", "renderRunCreation", "renderIteration", "renderEffects",
+            "renderBreakpointHandling", "renderResultsPosting", "renderLoopControl",
+            "renderCompletionProof", "renderQuickReference", "renderRecovery", "renderCriticalRules",
+        ],
+    },
+    "breakpoint-handling": {
+        fn: prompts_1.composeBreakpointPrompt,
+        promptType: "breakpoint-handling",
+        partsIncluded: ["breakpoint-handling", "results-posting"],
+        strataParts: ["renderBreakpointHandling", "renderResultsPosting"],
+    },
+};
+/**
+ * Resolve a PromptContext factory by harness name.
+ */
+function resolveContextFactory(harness) {
+    if (harness === "custom") {
+        return (overrides) => createPessimisticPromptContext(overrides);
+    }
+    if (!(0, registry_1.getAdapterByName)(harness)?.getPromptContext) {
+        return undefined;
+    }
+    return (overrides) => {
+        const context = (0, registry_1.createPromptContextForHarness)(harness, overrides);
+        if (!context) {
+            throw new Error(`Harness "${harness}" does not provide a prompt context.`);
+        }
+        return context;
+    };
+}
+function createPessimisticPromptContext(overrides) {
+    return (0, contextShared_1.createPromptContext)({
+        harness: "custom",
+        harnessLabel: "Custom Harness",
+        capabilities: ["task-tool", "breakpoint-routing"],
+        pluginRootVar: "",
+        loopControlTerm: "in-turn",
+        sessionBindingFlags: "",
+        hookDriven: false,
+        interactiveToolName: "",
+        sessionEnvVars: "`--session-id`, `AGENT_SESSION_ID`, or the PID-scoped session marker fallback",
+        resumeFlags: "",
+        cliSetupSnippet: (0, contextShared_1.createDefaultCliSetupSnippet)(),
+        iterateFlags: "",
+        hasIntentFidelityChecks: false,
+        hasNonNegotiables: false,
+    }, overrides);
+}
+function resolveInstructionsHarness(harness) {
+    if (harness) {
+        return {
+            harness,
+            source: "explicit",
+            warnings: [],
+            evidence: [],
+        };
+    }
+    const caller = (0, discovery_1.detectCallerHarness)();
+    if (caller) {
+        return {
+            harness: caller.name,
+            source: "caller",
+            warnings: [],
+            evidence: caller.matchedEnvVars,
+        };
+    }
+    const hooksMuxCaller = (0, discovery_1.detectCallerHarnessViaHooksMux)();
+    if (hooksMuxCaller) {
+        return {
+            harness: hooksMuxCaller.name,
+            source: "hooks-mux",
+            warnings: [],
+            evidence: hooksMuxCaller.matchedEnvVars,
+        };
+    }
+    return {
+        harness: "custom",
+        source: "fallback",
+        warnings: [
+            "Host discovery failed for `instructions:*`; using the pessimistic custom-harness prompt context.",
+        ],
+        evidence: [],
+    };
+}
+/**
+ * Try to resolve the active process-library root from the SDK directly.
+ * Returns the library root and reference root if a binding exists,
+ * or undefined values if resolution fails (no binding, network error, etc.).
+ */
+async function tryResolveProcessLibraryRoot() {
+    try {
+        const resolved = await (0, active_1.resolveActiveProcessLibrary)();
+        if (resolved.binding?.dir) {
+            const defaultSpec = (0, active_1.getDefaultProcessLibrarySpec)();
+            return {
+                processLibraryRoot: defaultSpec.processRoot,
+                processLibraryReferenceRoot: defaultSpec.referenceRoot,
+            };
+        }
+    }
+    catch {
+        // No binding exists or resolution failed — fall back to manual instructions
+    }
+    return {};
+}
+function detectHooksActive(harness) {
+    const adapter = (0, registry_1.getAdapterByName)(harness);
+    if (!adapter)
+        return false;
+    const sessionId = adapter.resolveSessionId({});
+    if (!sessionId)
+        return false;
+    const stateDir = adapter.resolveStateDir({});
+    if (!stateDir)
+        return false;
+    const stateFile = (0, parse_1.getSessionFilePath)(stateDir, sessionId);
+    return (0, node_fs_1.existsSync)(stateFile);
+}
+/**
+ * Route and handle an `instructions:*` subcommand.
+ */
+async function handleInstructionsCommand(args) {
+    const resolvedHarness = resolveInstructionsHarness(args.harness);
+    const factory = resolveContextFactory(resolvedHarness.harness);
+    if (!factory) {
+        const known = registry_1.KNOWN_HARNESSES.map((spec) => spec.name).join(", ");
+        if (args.json) {
+            console.log(JSON.stringify({
+                error: "unknown_harness",
+                message: `Unknown harness "${resolvedHarness.harness}". Known harnesses: ${known}`,
+            }));
+        }
+        else {
+            console.error(`[instructions] Unknown harness "${resolvedHarness.harness}". Known harnesses: ${known}`);
+        }
+        return 1;
+    }
+    const composer = COMPOSERS[args.subcommand];
+    if (!composer) {
+        const known = Object.keys(COMPOSERS).join(", ");
+        if (args.json) {
+            console.log(JSON.stringify({
+                error: "unknown_subcommand",
+                message: `Unknown subcommand "${args.subcommand}". Known subcommands: ${known}`,
+            }));
+        }
+        else {
+            console.error(`[instructions] Unknown subcommand "${args.subcommand}". Known subcommands: ${known}`);
+        }
+        return 1;
+    }
+    // Resolve the active process-library root before composing the prompt
+    const libraryInfo = await tryResolveProcessLibraryRoot();
+    // Detect whether hooks are actually active in this session.
+    // hookDriven=false when: non-interactive mode, or session-start hook never ran.
+    // Non-interactive mode never has hooks — the agent must drive the loop in-turn.
+    const hooksActive = args.interactive !== false && detectHooksActive(resolvedHarness.harness);
+    const hookOverride = {};
+    if (!hooksActive) {
+        hookOverride.hookDriven = false;
+    }
+    // Detect execution context (CI, trigger, branch, actor) and derive
+    // capability flags so the babysit skill can select context-appropriate
+    // library processes when dispatching (e.g. GitHub collaboration,
+    // scheduled reporting, local-dev relaxations).
+    const executionContext = (0, prompts_1.detectExecutionContext)();
+    const capabilityFlags = (0, prompts_1.deriveCapabilityFlags)(executionContext);
+    const existingRun = await (0, detectExistingRun_1.detectExistingRun)();
+    const ctx = factory({
+        interactive: args.interactive,
+        ...libraryInfo,
+        ...hookOverride,
+    });
+    // GAP-PROMPT-001: Use strata-aware composition when --show-strata is set
+    let content;
+    if (args.showStrata) {
+        const taggedParts = composer.strataParts
+            .map(name => prompts_1.PART_STRATA_MAP[name])
+            .filter((p) => p != null);
+        content = (0, prompts_1.composeByStrata)(taggedParts, ctx, { showStrata: true });
+    }
+    else {
+        content = composer.fn(ctx);
+    }
+    if (args.json) {
+        console.log(JSON.stringify({
+            harness: resolvedHarness.harness,
+            harnessSource: resolvedHarness.source,
+            discoveryEvidence: resolvedHarness.evidence,
+            interactive: args.interactive,
+            promptType: composer.promptType,
+            hookDriven: ctx.hookDriven,
+            hooksDetected: hooksActive,
+            warnings: resolvedHarness.warnings,
+            executionContext,
+            capabilityFlags,
+            suggestedProcesses: (0, prompts_1.processPathsForCapabilities)(capabilityFlags),
+            existingRun: existingRun ?? null,
+            content,
+            partsIncluded: composer.partsIncluded,
+        }, null, 2));
+    }
+    else {
+        for (const warning of resolvedHarness.warnings)
+            console.error(`[instructions] Warning: ${warning}`);
+        console.log(formatTextOutput(executionContext, capabilityFlags, existingRun, content));
+    }
+    return 0;
+}
+function formatTextOutput(executionContext, capabilityFlags, existingRun, content) {
+    const caps = Object.entries(capabilityFlags).filter(([, v]) => v).map(([k]) => k);
+    const header = [
+        '## Execution Context', '',
+        `- CI: \`${executionContext.ci}\``,
+        `- Trigger: \`${executionContext.trigger}\``,
+        executionContext.branch.ref ? `- Branch: \`${executionContext.branch.ref}\`` : undefined,
+        executionContext.repo ? `- Repo: \`${executionContext.repo.owner}/${executionContext.repo.name}\`` : undefined,
+        executionContext.actor ? `- Actor: \`${executionContext.actor.login}\`${executionContext.actor.isBot ? ' (bot)' : ''}` : undefined,
+        '', `Active context capabilities: ${caps.length > 0 ? caps.map(c => `\`${c}\``).join(', ') : '_(none)_'}`,
+        '', 'When selecting library processes to dispatch, prefer those whose triggers match the active capabilities above.', '', '---', '',
+    ].filter((l) => l !== undefined).join('\n');
+    const guide = (0, prompts_1.renderCapabilityProcessGuide)(capabilityFlags);
+    const runBlock = existingRun ? (0, detectExistingRun_1.formatExistingRunBlock)(existingRun) : '';
+    return header + guide + runBlock + content;
+}

package/dist/cli/commands/log.d.ts

@@ -0,0 +1,22 @@
+/**
+ * log CLI command.
+ *
+ * Writes a structured log entry to the appropriate contextual log file.
+ * Intended to be called from shell hooks and scripts as a canonical way
+ * to emit structured logs without embedding JSONL formatting inline.
+ *
+ * Usage:
+ *   babysitter log --type <process|hook|cli> --message <msg> [--run-id <id>] [--label <label>] [--level <level>] [--source <src>] [--json]
+ */
+export interface LogCommandArgs {
+    logType: string;
+    message: string;
+    runId?: string;
+    processId?: string;
+    label?: string;
+    level?: string;
+    source?: string;
+    json: boolean;
+}
+export declare function handleLog(args: LogCommandArgs): Promise<number>;
+//# sourceMappingURL=log.d.ts.map

package/dist/cli/commands/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAaD,wBAAsB,SAAS,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ErE"}

package/dist/cli/commands/log.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * log CLI command.
+ *
+ * Writes a structured log entry to the appropriate contextual log file.
+ * Intended to be called from shell hooks and scripts as a canonical way
+ * to emit structured logs without embedding JSONL formatting inline.
+ *
+ * Usage:
+ *   babysitter log --type <process|hook|cli> --message <msg> [--run-id <id>] [--label <label>] [--level <level>] [--source <src>] [--json]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleLog = handleLog;
+const runLogger_1 = require("../../logging/runLogger");
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+const VALID_LOG_TYPES = new Set(["process", "hook", "cli"]);
+const VALID_LOG_LEVELS = new Set(["debug", "info", "warn", "error"]);
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+async function handleLog(args) {
+    const { logType, message, runId, processId, label, source, json } = args;
+    const level = (args.level || "info");
+    if (!logType) {
+        const error = { error: "MISSING_LOG_TYPE", message: "--type is required (process, hook, cli)" };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write("Error: --type is required (process, hook, cli)\n");
+        }
+        return 1;
+    }
+    if (!VALID_LOG_TYPES.has(logType)) {
+        const error = {
+            error: "INVALID_LOG_TYPE",
+            message: `Invalid log type: "${logType}". Must be one of: process, hook, cli`,
+        };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write(`Error: ${error.message}\n`);
+        }
+        return 1;
+    }
+    if (!message) {
+        const error = { error: "MISSING_MESSAGE", message: "--message is required" };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write("Error: --message is required\n");
+        }
+        return 1;
+    }
+    if (!VALID_LOG_LEVELS.has(level)) {
+        const error = {
+            error: "INVALID_LOG_LEVEL",
+            message: `Invalid log level: "${level}". Must be one of: debug, info, warn, error`,
+        };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write(`Error: ${error.message}\n`);
+        }
+        return 1;
+    }
+    try {
+        const logPath = await (0, runLogger_1.appendRunLog)({
+            timestamp: new Date().toISOString(),
+            level,
+            type: logType,
+            label: label || undefined,
+            message,
+            runId: runId || undefined,
+            processId: processId || undefined,
+            source: source || undefined,
+        });
+        if (json) {
+            console.log(JSON.stringify({ ok: true, logPath }));
+        }
+        return 0;
+    }
+    catch (e) {
+        const errMsg = e instanceof Error ? e.message : String(e);
+        const error = { error: "LOG_WRITE_FAILED", message: errMsg };
+        if (json) {
+            process.stderr.write(JSON.stringify(error, null, 2) + "\n");
+        }
+        else {
+            process.stderr.write(`Error: Failed to write log: ${errMsg}\n`);
+        }
+        return 1;
+    }
+}