@groundtrack/hooks 0.1.9 → 0.1.11

package/dist/session-import/normalize.js

@@ -0,0 +1,100 @@
+import { CANONICAL_IMPORT_MAX_ENTRIES, isSessionRecord, sessionString, } from "./canonical.js";
+import { sanitizeRepositoryUrl } from "./redaction.js";
+export class SessionNormalizationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SessionNormalizationError";
+        this.code = code;
+    }
+}
+function recordTimestamp(record) {
+    const value = sessionString(record.timestamp);
+    if (!value)
+        return null;
+    const timestamp = new Date(value).getTime();
+    return Number.isNaN(timestamp) ? null : timestamp;
+}
+export function createSessionNormalizationAccumulator(normalizer, options = {}) {
+    const entries = [];
+    let totalRecordCount = 0;
+    let importedRecordCount = 0;
+    let importedEntryCount = 0;
+    let malformedRecordCount = 0;
+    let sensitiveRecordCount = 0;
+    let unsupportedRecordCount = 0;
+    let earliestTimestampMs = options.discoveryMetadata?.startedAt?.getTime() ?? null;
+    let latestTimestampMs = options.discoveryMetadata?.endedAt?.getTime() ?? null;
+    return {
+        add(record) {
+            totalRecordCount += 1;
+            if (!isSessionRecord(record)) {
+                malformedRecordCount += 1;
+                return;
+            }
+            const timestamp = recordTimestamp(record);
+            if (timestamp !== null) {
+                earliestTimestampMs =
+                    earliestTimestampMs === null ? timestamp : Math.min(earliestTimestampMs, timestamp);
+                latestTimestampMs =
+                    latestTimestampMs === null ? timestamp : Math.max(latestTimestampMs, timestamp);
+            }
+            const normalized = normalizer.normalizeRecord(record, CANONICAL_IMPORT_MAX_ENTRIES - importedEntryCount);
+            if (normalized.sensitive)
+                sensitiveRecordCount += 1;
+            if (normalized.unsupported)
+                unsupportedRecordCount += 1;
+            if (normalized.overflowed)
+                throw new SessionNormalizationError("too_many_entries", `Session has too many entries (maximum ${CANONICAL_IMPORT_MAX_ENTRIES}).`);
+            if (normalized.entries.length > 0)
+                importedRecordCount += 1;
+            for (const entry of normalized.entries) {
+                importedEntryCount += 1;
+                if (importedEntryCount > CANONICAL_IMPORT_MAX_ENTRIES)
+                    throw new SessionNormalizationError("too_many_entries", `Session has too many entries (maximum ${CANONICAL_IMPORT_MAX_ENTRIES}).`);
+                if (options.collectEntries)
+                    entries.push(entry);
+                options.onEntry?.(entry);
+            }
+        },
+        finish() {
+            const base = normalizer.canonicalMetadata();
+            if (!base)
+                throw new SessionNormalizationError("missing_session_metadata", "Session metadata is missing.");
+            if (importedEntryCount === 0)
+                throw new SessionNormalizationError("empty_trace", "Session has no supported trace entries.");
+            return {
+                metadata: {
+                    ...base,
+                    repositoryUrl: options.discoveryMetadata
+                        ? sanitizeRepositoryUrl(options.discoveryMetadata.repositoryUrl)
+                        : base.repositoryUrl,
+                    startedAt: earliestTimestampMs === null
+                        ? (options.discoveryMetadata?.startedAt?.toISOString() ?? null)
+                        : new Date(earliestTimestampMs).toISOString(),
+                    endedAt: latestTimestampMs === null
+                        ? (options.discoveryMetadata?.endedAt?.toISOString() ?? null)
+                        : new Date(latestTimestampMs).toISOString(),
+                    statistics: {
+                        totalRecordCount,
+                        importedEntryCount,
+                        skippedRecordCount: totalRecordCount - importedRecordCount,
+                        unsupportedRecordCount,
+                        malformedRecordCount,
+                        sensitiveRecordCount,
+                    },
+                },
+                entries,
+            };
+        },
+    };
+}
+export function normalizeSessionRecords(records, normalizer, discoveryMetadata) {
+    const accumulator = createSessionNormalizationAccumulator(normalizer, {
+        discoveryMetadata,
+        collectEntries: true,
+    });
+    for (const record of records)
+        accumulator.add(record);
+    return accumulator.finish();
+}

package/dist/session-import/opencode-cli.d.ts

@@ -0,0 +1,14 @@
+import { type MaterializedSessionCandidates, type SessionDiscoveryCandidates, type SessionDiscoveryContext, type SessionImportFormat } from "./format.js";
+import type { AgentSessionCandidate } from "./types.js";
+type OpenCodeSessionRow = Readonly<{
+    id?: unknown;
+    projectID?: unknown;
+    parentID?: unknown;
+    directory?: unknown;
+    created?: unknown;
+    updated?: unknown;
+}>;
+export declare function opencodeCandidates(context: SessionDiscoveryContext, rows?: readonly OpenCodeSessionRow[]): SessionDiscoveryCandidates;
+export declare function materializeOpenCodeCandidates(candidates: readonly AgentSessionCandidate[], context: SessionDiscoveryContext): MaterializedSessionCandidates;
+export declare const opencodeSessionFormat: SessionImportFormat;
+export {};

package/dist/session-import/opencode-cli.js

@@ -0,0 +1,178 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, closeSync, constants, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, utimesSync, writeSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isSessionRecord, sessionString } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
+import { createOpenCodeSessionNormalizer, parseOpenCodeSessionExport } from "./opencode.js";
+const inventoryQuery = `
+  SELECT
+    id,
+    project_id AS projectID,
+    parent_id AS parentID,
+    directory,
+    time_created AS created,
+    time_updated AS updated
+  FROM session
+  ORDER BY time_updated ASC, id ASC
+`;
+function timestamp(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function openCodeBinary(context) {
+    return context.env.OPENCODE_BIN || "opencode";
+}
+function runOpenCodeToFile(context, args, outputPath) {
+    const output = openSync(outputPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    let result;
+    try {
+        result = spawnSync(openCodeBinary(context), args, {
+            cwd: context.workingDirectory,
+            env: context.env,
+            encoding: "utf8",
+            stdio: ["ignore", output, "pipe"],
+            timeout: 120_000,
+            maxBuffer: 1024 * 1024,
+        });
+    }
+    finally {
+        closeSync(output);
+    }
+    if (result.error) {
+        if (result.error.code === "ENOENT")
+            throw new Error("OpenCode session import requires the opencode CLI. Install it or set OPENCODE_BIN.");
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        const detail = typeof result.stderr === "string" ? result.stderr.trim() : "";
+        throw new Error(`OpenCode command failed (${result.status ?? "unknown"})${detail ? `: ${detail}` : "."}`);
+    }
+}
+function readJsonFile(path, label) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`OpenCode returned invalid ${label} JSON.`);
+    }
+}
+function withCommandOutput(context, args, label, read) {
+    const directory = mkdtempSync(join(tmpdir(), "groundtrack-opencode-command-"));
+    chmodSync(directory, 0o700);
+    try {
+        const path = join(directory, "output.json");
+        runOpenCodeToFile(context, args, path);
+        return read(readJsonFile(path, label));
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+}
+function readInventory(context) {
+    return withCommandOutput(context, ["db", inventoryQuery, "--format", "json", "--pure"], "session inventory", (value) => {
+        if (!Array.isArray(value) || !value.every(isSessionRecord))
+            throw new Error("OpenCode returned an invalid session inventory.");
+        return value;
+    });
+}
+export function opencodeCandidates(context, rows = readInventory(context)) {
+    const included = [];
+    const skipped = [];
+    for (const row of rows) {
+        const externalSessionId = sessionString(row.id);
+        const cwd = sessionString(row.directory);
+        const startedAt = timestamp(row.created);
+        const endedAt = timestamp(row.updated);
+        const path = externalSessionId ? `opencode:${externalSessionId}` : "opencode:unknown";
+        if (!externalSessionId || !startedAt || !endedAt || endedAt < startedAt) {
+            skipped.push({ path, reason: "invalid_metadata" });
+            continue;
+        }
+        included.push({
+            path,
+            modifiedAt: endedAt,
+            metadata: {
+                externalSessionId,
+                timestamp: endedAt,
+                cwd,
+                repositoryUrl: null,
+                repositoryBranch: null,
+                repositoryCommitSha: null,
+                originator: "opencode",
+                isSubagent: sessionString(row.parentID) !== null,
+                startedAt,
+                endedAt,
+            },
+        });
+    }
+    return { included, skipped };
+}
+function writeJsonLine(file, value) {
+    writeSync(file, `${JSON.stringify(value)}\n`);
+}
+function materializeExport(context, candidate, directory, index) {
+    const rawPath = join(directory, `raw-${index}.json`);
+    runOpenCodeToFile(context, ["export", candidate.metadata.externalSessionId, "--pure"], rawPath);
+    let data;
+    try {
+        data = readJsonFile(rawPath, "session export");
+    }
+    finally {
+        unlinkSync(rawPath);
+    }
+    const decoded = parseOpenCodeSessionExport(data);
+    if (!decoded)
+        throw new Error("OpenCode returned an invalid session export.");
+    if (decoded.metadata.externalSessionId !== candidate.metadata.externalSessionId)
+        throw new Error("OpenCode exported a different session than requested.");
+    const path = join(directory, `session-${index}.jsonl`);
+    const file = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    try {
+        for (const record of decoded.records)
+            writeJsonLine(file, record);
+    }
+    finally {
+        closeSync(file);
+    }
+    const modifiedAt = candidate.modifiedAt ?? candidate.metadata.timestamp;
+    if (modifiedAt)
+        utimesSync(path, modifiedAt, modifiedAt);
+    return { ...candidate, path };
+}
+export function materializeOpenCodeCandidates(candidates, context) {
+    if (candidates.length === 0)
+        return { included: [], failed: [], cleanup() { } };
+    const directory = mkdtempSync(join(tmpdir(), "groundtrack-opencode-import-"));
+    chmodSync(directory, 0o700);
+    const included = [];
+    const failed = [];
+    for (const [index, candidate] of candidates.entries()) {
+        try {
+            included.push(materializeExport(context, candidate, directory, index));
+        }
+        catch (error) {
+            failed.push({
+                path: candidate.path,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        included,
+        failed,
+        cleanup: () => rmSync(directory, { recursive: true, force: true }),
+    };
+}
+export const opencodeSessionFormat = {
+    ...sessionImportFormatIdentity("opencode"),
+    discovery: "custom",
+    homeEnvironmentVariable: "XDG_DATA_HOME",
+    defaultHomeDirectory: ".local/share",
+    discoverCandidates: opencodeCandidates,
+    materializeCandidates: materializeOpenCodeCandidates,
+    createNormalizer: createOpenCodeSessionNormalizer,
+    sourceHashSeed: (metadata) => metadata.externalSessionId,
+};

package/dist/session-import/opencode-normalizer.d.ts

@@ -0,0 +1,8 @@
+import type { SessionNormalizer } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+export type DecodedOpenCodeSession = Readonly<{
+    metadata: AgentSessionMetadata;
+    records: readonly unknown[];
+}>;
+export declare function decodeOpenCodeSessionExport(value: unknown): DecodedOpenCodeSession | null;
+export declare function createOpenCodeSessionNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;

package/dist/session-import/opencode-normalizer.js

@@ -0,0 +1,230 @@
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { containsInternalInstructionText, redactCredentialText, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
+function unixMillisecondsDate(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function messageTimestamp(message) {
+    const info = isSessionRecord(message.info) ? message.info : {};
+    const time = isSessionRecord(info.time) ? info.time : {};
+    return (unixMillisecondsDate(time.completed)?.toISOString() ??
+        unixMillisecondsDate(time.created)?.toISOString() ??
+        null);
+}
+export function decodeOpenCodeSessionExport(value) {
+    if (!isSessionRecord(value) || !isSessionRecord(value.info) || !Array.isArray(value.messages))
+        return null;
+    const externalSessionId = sessionString(value.info.id);
+    if (!externalSessionId)
+        return null;
+    const time = isSessionRecord(value.info.time) ? value.info.time : {};
+    const startedAt = unixMillisecondsDate(time.created);
+    const endedAt = unixMillisecondsDate(time.updated);
+    return {
+        metadata: {
+            externalSessionId,
+            timestamp: endedAt ?? startedAt,
+            cwd: sessionString(value.info.directory),
+            repositoryUrl: null,
+            repositoryBranch: null,
+            repositoryCommitSha: null,
+            originator: "opencode",
+            isSubagent: sessionString(value.info.parentID) !== null,
+            startedAt,
+            endedAt,
+        },
+        records: [
+            {
+                type: "opencode_session",
+                timestamp: startedAt?.toISOString() ?? null,
+                info: {
+                    id: value.info.id,
+                    directory: value.info.directory,
+                    model: value.info.model,
+                    version: value.info.version,
+                },
+            },
+            ...value.messages.map((message) => isSessionRecord(message)
+                ? {
+                    type: "opencode_message",
+                    timestamp: messageTimestamp(message),
+                    info: message.info,
+                    parts: message.parts,
+                }
+                : message),
+        ],
+    };
+}
+function timestampIso(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function modelName(value) {
+    if (typeof value === "string")
+        return value || null;
+    if (!isSessionRecord(value))
+        return null;
+    const provider = sessionString(value.providerID);
+    const model = sessionString(value.modelID) ?? sessionString(value.id);
+    return provider && model ? `${provider}/${model}` : model;
+}
+function containsInternalInstructions(value) {
+    if (typeof value === "string")
+        return containsInternalInstructionText(value);
+    if (Array.isArray(value))
+        return value.some(containsInternalInstructions);
+    if (!isSessionRecord(value))
+        return false;
+    return Object.values(value).some(containsInternalInstructions);
+}
+function redactHomePaths(value) {
+    if (typeof value === "string")
+        return value
+            .replace(/\/Users\/[^/\s"'`]+/g, "~")
+            .replace(/\/home\/[^/\s"'`]+/g, "~")
+            .replace(/[A-Za-z]:\\Users\\[^\\\s"'`]+/gi, "~");
+    if (Array.isArray(value))
+        return value.map(redactHomePaths);
+    if (!isSessionRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, redactHomePaths(nested)]));
+}
+function sanitizeOpenCodeValue(value) {
+    return redactHomePaths(sanitizeSessionValue(value));
+}
+function safeValue(value) {
+    return containsInternalInstructions(value)
+        ? "[REDACTED INTERNAL INSTRUCTIONS]"
+        : sanitizeOpenCodeValue(value);
+}
+function partTimestamp(part, key, fallback) {
+    const state = isSessionRecord(part.state) ? part.state : {};
+    const time = isSessionRecord(state.time) ? state.time : {};
+    return timestampIso(time[key]) ?? fallback;
+}
+function normalizeOpenCodeMessage(record, entryBudget) {
+    const info = isSessionRecord(record.info) ? record.info : null;
+    const role = info ? sessionString(info.role) : null;
+    if (!info || (role !== "user" && role !== "assistant") || !Array.isArray(record.parts))
+        return { entries: [], sensitive: false, unsupported: true };
+    const occurredAt = sessionString(record.timestamp);
+    const entries = [];
+    let sensitive = false;
+    let unsupported = false;
+    for (const part of record.parts) {
+        if (entries.length > entryBudget)
+            break;
+        if (!isSessionRecord(part)) {
+            unsupported = true;
+            continue;
+        }
+        const type = sessionString(part.type);
+        if (type === "reasoning" || type === "file" || type === "patch" || type === "snapshot") {
+            sensitive = true;
+            continue;
+        }
+        if (type === "text") {
+            const text = sessionString(part.text);
+            if (!text || part.ignored === true)
+                continue;
+            if (part.synthetic === true || containsInternalInstructionText(text))
+                sensitive = true;
+            else
+                entries.push({
+                    kind: role === "user" ? "user_message" : "assistant_message",
+                    occurredAt,
+                    payload: { text: sanitizeOpenCodeValue(text) },
+                });
+            continue;
+        }
+        if (type === "tool" && role === "assistant") {
+            const toolName = sessionString(part.tool);
+            const state = isSessionRecord(part.state) ? part.state : null;
+            if (!toolName || !state) {
+                unsupported = true;
+                continue;
+            }
+            const inputContainsInternalInstructions = containsInternalInstructions(state.input);
+            sensitive ||= inputContainsInternalInstructions;
+            entries.push({
+                kind: "tool_call",
+                occurredAt: partTimestamp(part, "start", occurredAt),
+                payload: {
+                    callId: sessionString(part.callID),
+                    toolName: redactCredentialText(toolName),
+                    input: inputContainsInternalInstructions
+                        ? "[REDACTED INTERNAL INSTRUCTIONS]"
+                        : sanitizeOpenCodeValue(state.input),
+                },
+            });
+            const status = sessionString(state.status);
+            if (status === "completed" || status === "error") {
+                const output = status === "completed" ? state.output : state.error;
+                const outputContainsInternalInstructions = containsInternalInstructions(output);
+                sensitive ||= outputContainsInternalInstructions;
+                entries.push({
+                    kind: "tool_result",
+                    occurredAt: partTimestamp(part, "end", occurredAt),
+                    payload: {
+                        callId: sessionString(part.callID),
+                        output: safeValue(output),
+                        ...(status === "error" ? { isError: true } : {}),
+                    },
+                });
+            }
+            continue;
+        }
+        if (type === "step-start" ||
+            type === "step-finish" ||
+            type === "retry" ||
+            type === "compaction")
+            continue;
+        if (type === "subtask" || type === "agent")
+            sensitive = true;
+        else
+            unsupported = true;
+    }
+    const overflowed = entries.length > entryBudget;
+    return {
+        entries: overflowed ? entries.slice(0, entryBudget) : entries,
+        sensitive,
+        unsupported,
+        overflowed,
+    };
+}
+export function createOpenCodeSessionNormalizer(metadata) {
+    let model = null;
+    return {
+        normalizeRecord: (record, entryBudget = Number.POSITIVE_INFINITY) => {
+            if (record.type === "opencode_session") {
+                const info = isSessionRecord(record.info) ? record.info : {};
+                model ??= modelName(info.model);
+                return { entries: [], sensitive: false, unsupported: false };
+            }
+            if (record.type !== "opencode_message")
+                return { entries: [], sensitive: false, unsupported: true };
+            const info = isSessionRecord(record.info) ? record.info : {};
+            const provider = sessionString(info.providerID);
+            const modelId = sessionString(info.modelID);
+            model ??= provider && modelId ? `${provider}/${modelId}` : modelId;
+            return normalizeOpenCodeMessage(record, entryBudget);
+        },
+        canonicalMetadata: () => metadata
+            ? {
+                type: "session",
+                version: 1,
+                externalSessionId: metadata.externalSessionId,
+                repositoryUrl: metadata.repositoryUrl,
+                repositoryBranch: metadata.repositoryBranch,
+                repositoryCommitSha: metadata.repositoryCommitSha,
+                workingDirectory: sanitizeWorkingDirectory(metadata.cwd),
+                originator: "opencode",
+                model: model ? redactCredentialText(model) : null,
+            }
+            : null,
+    };
+}

package/dist/session-import/opencode.d.ts

@@ -0,0 +1,8 @@
+import type { SessionNormalizer } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+export type DecodedOpenCodeSession = Readonly<{
+    metadata: AgentSessionMetadata;
+    records: readonly unknown[];
+}>;
+export declare function parseOpenCodeSessionExport(value: unknown): DecodedOpenCodeSession | null;
+export declare function createOpenCodeSessionNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;