@aexol/spectral 0.7.0 → 0.7.3

package/dist/pi/agent-core/harness/prompt-templates.js

@@ -0,0 +1,229 @@
+import { parse } from "yaml";
+import { toError } from "./types.js";
+/**
+ * Load prompt templates from one or more paths.
+ *
+ * Directory inputs load direct `.md` children non-recursively. File inputs load explicit `.md` files. Missing paths and
+ * non-markdown files are skipped. Read and parse failures are returned as diagnostics.
+ */
+export async function loadPromptTemplates(env, paths) {
+    const promptTemplates = [];
+    const diagnostics = [];
+    for (const path of Array.isArray(paths) ? paths : [paths]) {
+        const infoResult = await env.fileInfo(path);
+        if (!infoResult.ok) {
+            if (infoResult.error.code !== "not_found") {
+                diagnostics.push({
+                    type: "warning",
+                    code: "file_info_failed",
+                    message: infoResult.error.message,
+                    path,
+                });
+            }
+            continue;
+        }
+        const info = infoResult.value;
+        const kind = await resolveKind(env, info, diagnostics);
+        if (kind === "directory") {
+            const result = await loadTemplatesFromDir(env, info.path);
+            promptTemplates.push(...result.promptTemplates);
+            diagnostics.push(...result.diagnostics);
+        }
+        else if (kind === "file" && info.name.endsWith(".md")) {
+            const result = await loadTemplateFromFile(env, info.path);
+            if (result.promptTemplate)
+                promptTemplates.push(result.promptTemplate);
+            diagnostics.push(...result.diagnostics);
+        }
+    }
+    return { promptTemplates, diagnostics };
+}
+/**
+ * Load prompt templates from source-tagged paths.
+ *
+ * Source values are preserved exactly and attached to every loaded prompt template and diagnostic. The agent package does
+ * not interpret source values; applications define their own provenance shape.
+ */
+export async function loadSourcedPromptTemplates(env, inputs, mapPromptTemplate) {
+    const promptTemplates = [];
+    const diagnostics = [];
+    for (const input of inputs) {
+        const result = await loadPromptTemplates(env, input.path);
+        for (const promptTemplate of result.promptTemplates) {
+            promptTemplates.push({
+                promptTemplate: mapPromptTemplate
+                    ? mapPromptTemplate(promptTemplate, input.source)
+                    : promptTemplate,
+                source: input.source,
+            });
+        }
+        for (const diagnostic of result.diagnostics)
+            diagnostics.push({ ...diagnostic, source: input.source });
+    }
+    return { promptTemplates, diagnostics };
+}
+async function loadTemplatesFromDir(env, dir) {
+    const promptTemplates = [];
+    const diagnostics = [];
+    const entriesResult = await env.listDir(dir);
+    if (!entriesResult.ok) {
+        diagnostics.push({
+            type: "warning",
+            code: "list_failed",
+            message: entriesResult.error.message,
+            path: dir,
+        });
+        return { promptTemplates, diagnostics };
+    }
+    const entries = entriesResult.value;
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const kind = await resolveKind(env, entry, diagnostics);
+        if (kind !== "file" || !entry.name.endsWith(".md"))
+            continue;
+        const result = await loadTemplateFromFile(env, entry.path);
+        if (result.promptTemplate)
+            promptTemplates.push(result.promptTemplate);
+        diagnostics.push(...result.diagnostics);
+    }
+    return { promptTemplates, diagnostics };
+}
+async function loadTemplateFromFile(env, filePath) {
+    const diagnostics = [];
+    const rawContent = await env.readTextFile(filePath);
+    if (!rawContent.ok) {
+        diagnostics.push({
+            type: "warning",
+            code: "read_failed",
+            message: rawContent.error.message,
+            path: filePath,
+        });
+        return { promptTemplate: null, diagnostics };
+    }
+    const parsed = parseFrontmatter(rawContent.value);
+    if (!parsed.ok) {
+        diagnostics.push({
+            type: "warning",
+            code: "parse_failed",
+            message: parsed.error.message,
+            path: filePath,
+        });
+        return { promptTemplate: null, diagnostics };
+    }
+    const { frontmatter, body } = parsed.value;
+    const firstLine = body.split("\n").find((line) => line.trim());
+    let description = typeof frontmatter.description === "string" ? frontmatter.description : "";
+    if (!description && firstLine) {
+        description = firstLine.slice(0, 60);
+        if (firstLine.length > 60)
+            description += "...";
+    }
+    return {
+        promptTemplate: {
+            name: basenameEnvPath(filePath).replace(/\.md$/i, ""),
+            description,
+            content: body,
+        },
+        diagnostics,
+    };
+}
+async function resolveKind(env, info, diagnostics) {
+    if (info.kind === "file" || info.kind === "directory")
+        return info.kind;
+    const canonicalPath = await env.canonicalPath(info.path);
+    if (!canonicalPath.ok) {
+        if (canonicalPath.error.code !== "not_found") {
+            diagnostics.push({
+                type: "warning",
+                code: "file_info_failed",
+                message: canonicalPath.error.message,
+                path: info.path,
+            });
+        }
+        return undefined;
+    }
+    const target = await env.fileInfo(canonicalPath.value);
+    if (!target.ok) {
+        if (target.error.code !== "not_found") {
+            diagnostics.push({
+                type: "warning",
+                code: "file_info_failed",
+                message: target.error.message,
+                path: info.path,
+            });
+        }
+        return undefined;
+    }
+    return target.value.kind === "file" || target.value.kind === "directory" ? target.value.kind : undefined;
+}
+function parseFrontmatter(content) {
+    try {
+        const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+        if (!normalized.startsWith("---"))
+            return { ok: true, value: { frontmatter: {}, body: normalized } };
+        const endIndex = normalized.indexOf("\n---", 3);
+        if (endIndex === -1)
+            return { ok: true, value: { frontmatter: {}, body: normalized } };
+        const yamlString = normalized.slice(4, endIndex);
+        const body = normalized.slice(endIndex + 4).trim();
+        return { ok: true, value: { frontmatter: (parse(yamlString) ?? {}), body } };
+    }
+    catch (error) {
+        return { ok: false, error: toError(error) };
+    }
+}
+function basenameEnvPath(path) {
+    const normalized = path.replace(/\/+$/, "");
+    const slashIndex = normalized.lastIndexOf("/");
+    return slashIndex === -1 ? normalized : normalized.slice(slashIndex + 1);
+}
+/** Parse an argument string using simple shell-style single and double quotes. */
+export function parseCommandArgs(argsString) {
+    const args = [];
+    let current = "";
+    let inQuote = null;
+    for (let i = 0; i < argsString.length; i++) {
+        const char = argsString[i];
+        if (inQuote) {
+            if (char === inQuote)
+                inQuote = null;
+            else
+                current += char;
+        }
+        else if (char === '"' || char === "'") {
+            inQuote = char;
+        }
+        else if (char === " " || char === "\t") {
+            if (current) {
+                args.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current)
+        args.push(current);
+    return args;
+}
+/** Substitute prompt template placeholders (`$1`, `$@`, `$ARGUMENTS`, `${@:N}`, `${@:N:L}`) with command arguments. */
+export function substituteArgs(content, args) {
+    let result = content;
+    result = result.replace(/\$(\d+)/g, (_, num) => args[parseInt(num, 10) - 1] ?? "");
+    result = result.replace(/\$\{@:(\d+)(?::(\d+))?\}/g, (_, startStr, lengthStr) => {
+        let start = parseInt(startStr, 10) - 1;
+        if (start < 0)
+            start = 0;
+        if (lengthStr)
+            return args.slice(start, start + parseInt(lengthStr, 10)).join(" ");
+        return args.slice(start).join(" ");
+    });
+    const allArgs = args.join(" ");
+    result = result.replace(/\$ARGUMENTS/g, allArgs);
+    result = result.replace(/\$@/g, allArgs);
+    return result;
+}
+/** Format a prompt template invocation with positional arguments. */
+export function formatPromptTemplateInvocation(template, args = []) {
+    return substituteArgs(template.content, args);
+}

package/dist/pi/agent-core/harness/session/jsonl-repo.js

@@ -0,0 +1,100 @@
+import { SessionError, toError } from "../types.js";
+import { JsonlSessionStorage, loadJsonlSessionMetadata } from "./jsonl-storage.js";
+import { createSessionId, createTimestamp, getEntriesToFork, getFileSystemResultOrThrow, toSession, } from "./repo-utils.js";
+function encodeCwd(cwd) {
+    return `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+export class JsonlSessionRepo {
+    fs;
+    sessionsRootInput;
+    sessionsRoot;
+    constructor(options) {
+        this.fs = options.fs;
+        this.sessionsRootInput = options.sessionsRoot;
+    }
+    async getSessionsRoot() {
+        if (!this.sessionsRoot) {
+            this.sessionsRoot = getFileSystemResultOrThrow(await this.fs.absolutePath(this.sessionsRootInput), `Failed to resolve sessions root ${this.sessionsRootInput}`);
+        }
+        return this.sessionsRoot;
+    }
+    async getSessionDir(cwd) {
+        return getFileSystemResultOrThrow(await this.fs.joinPath([await this.getSessionsRoot(), encodeCwd(cwd)]), `Failed to resolve session directory for ${cwd}`);
+    }
+    async createSessionFilePath(cwd, sessionId, timestamp) {
+        return getFileSystemResultOrThrow(await this.fs.joinPath([
+            await this.getSessionDir(cwd),
+            `${timestamp.replace(/[:.]/g, "-")}_${sessionId}.jsonl`,
+        ]), `Failed to resolve session file path for ${sessionId}`);
+    }
+    async create(options) {
+        const id = options.id ?? createSessionId();
+        const createdAt = createTimestamp();
+        const sessionDir = await this.getSessionDir(options.cwd);
+        getFileSystemResultOrThrow(await this.fs.createDir(sessionDir, { recursive: true }), `Failed to create session directory ${sessionDir}`);
+        const filePath = await this.createSessionFilePath(options.cwd, id, createdAt);
+        const storage = await JsonlSessionStorage.create(this.fs, filePath, {
+            cwd: options.cwd,
+            sessionId: id,
+            parentSessionPath: options.parentSessionPath,
+        });
+        return toSession(storage);
+    }
+    async open(metadata) {
+        if (!getFileSystemResultOrThrow(await this.fs.exists(metadata.path), `Failed to check session ${metadata.path}`)) {
+            throw new SessionError("not_found", `Session not found: ${metadata.path}`);
+        }
+        const storage = await JsonlSessionStorage.open(this.fs, metadata.path);
+        return toSession(storage);
+    }
+    async list(options = {}) {
+        const dirs = options.cwd ? [await this.getSessionDir(options.cwd)] : await this.listSessionDirs();
+        const sessions = [];
+        for (const dir of dirs) {
+            if (!getFileSystemResultOrThrow(await this.fs.exists(dir), `Failed to check session directory ${dir}`)) {
+                continue;
+            }
+            const files = getFileSystemResultOrThrow(await this.fs.listDir(dir), `Failed to list sessions in ${dir}`).filter((file) => file.kind !== "directory" && file.name.endsWith(".jsonl"));
+            for (const file of files) {
+                try {
+                    sessions.push(await loadJsonlSessionMetadata(this.fs, file.path));
+                }
+                catch (error) {
+                    const cause = toError(error);
+                    if (!(cause instanceof SessionError) || cause.code !== "invalid_session")
+                        throw cause;
+                }
+            }
+        }
+        sessions.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+        return sessions;
+    }
+    async delete(metadata) {
+        getFileSystemResultOrThrow(await this.fs.remove(metadata.path, { force: true }), `Failed to delete session ${metadata.path}`);
+    }
+    async fork(sourceMetadata, options) {
+        const source = await this.open(sourceMetadata);
+        const forkedEntries = await getEntriesToFork(source.getStorage(), options);
+        const id = options.id ?? createSessionId();
+        const createdAt = createTimestamp();
+        const sessionDir = await this.getSessionDir(options.cwd);
+        getFileSystemResultOrThrow(await this.fs.createDir(sessionDir, { recursive: true }), `Failed to create session directory ${sessionDir}`);
+        const storage = await JsonlSessionStorage.create(this.fs, await this.createSessionFilePath(options.cwd, id, createdAt), {
+            cwd: options.cwd,
+            sessionId: id,
+            parentSessionPath: options.parentSessionPath ?? sourceMetadata.path,
+        });
+        for (const entry of forkedEntries) {
+            await storage.appendEntry(entry);
+        }
+        return toSession(storage);
+    }
+    async listSessionDirs() {
+        const sessionsRoot = await this.getSessionsRoot();
+        if (!getFileSystemResultOrThrow(await this.fs.exists(sessionsRoot), `Failed to check sessions root ${sessionsRoot}`)) {
+            return [];
+        }
+        const entries = getFileSystemResultOrThrow(await this.fs.listDir(sessionsRoot), `Failed to list sessions root ${sessionsRoot}`);
+        return entries.filter((entry) => entry.kind === "directory").map((entry) => entry.path);
+    }
+}

package/dist/pi/agent-core/harness/session/jsonl-storage.js

@@ -0,0 +1,230 @@
+import { SessionError, toError } from "../types.js";
+import { getFileSystemResultOrThrow } from "./repo-utils.js";
+import { uuidv7 } from "./uuid.js";
+function updateLabelCache(labelsById, entry) {
+    if (entry.type !== "label")
+        return;
+    const label = entry.label?.trim();
+    if (label) {
+        labelsById.set(entry.targetId, label);
+    }
+    else {
+        labelsById.delete(entry.targetId);
+    }
+}
+function buildLabelsById(entries) {
+    const labelsById = new Map();
+    for (const entry of entries) {
+        updateLabelCache(labelsById, entry);
+    }
+    return labelsById;
+}
+function generateEntryId(byId) {
+    for (let i = 0; i < 100; i++) {
+        const id = uuidv7().slice(0, 8);
+        if (!byId.has(id))
+            return id;
+    }
+    return uuidv7();
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function invalidSession(filePath, message, cause) {
+    return new SessionError("invalid_session", `Invalid JSONL session file ${filePath}: ${message}`, cause);
+}
+function invalidEntry(filePath, lineNumber, message, cause) {
+    return new SessionError("invalid_entry", `Invalid JSONL session file ${filePath}: line ${lineNumber} ${message}`, cause);
+}
+function parseHeaderLine(line, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (error) {
+        throw invalidSession(filePath, "first line is not a valid session header", toError(error));
+    }
+    if (!isRecord(parsed))
+        throw invalidSession(filePath, "first line is not a valid session header");
+    if (parsed.type !== "session")
+        throw invalidSession(filePath, "first line is not a valid session header");
+    if (parsed.version !== 3)
+        throw invalidSession(filePath, "unsupported session version");
+    if (typeof parsed.id !== "string" || !parsed.id)
+        throw invalidSession(filePath, "session header is missing id");
+    if (typeof parsed.timestamp !== "string" || !parsed.timestamp) {
+        throw invalidSession(filePath, "session header is missing timestamp");
+    }
+    if (typeof parsed.cwd !== "string" || !parsed.cwd)
+        throw invalidSession(filePath, "session header is missing cwd");
+    if (parsed.parentSession !== undefined && typeof parsed.parentSession !== "string") {
+        throw invalidSession(filePath, "session header parentSession must be a string");
+    }
+    return {
+        type: "session",
+        version: 3,
+        id: parsed.id,
+        timestamp: parsed.timestamp,
+        cwd: parsed.cwd,
+        parentSession: parsed.parentSession,
+    };
+}
+function parseEntryLine(line, filePath, lineNumber) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch (error) {
+        throw invalidEntry(filePath, lineNumber, "is not valid JSON", toError(error));
+    }
+    if (!isRecord(parsed))
+        throw invalidEntry(filePath, lineNumber, "is not a valid session entry");
+    if (typeof parsed.type !== "string")
+        throw invalidEntry(filePath, lineNumber, "is missing entry type");
+    if (typeof parsed.id !== "string" || !parsed.id)
+        throw invalidEntry(filePath, lineNumber, "is missing entry id");
+    if (parsed.parentId !== null && typeof parsed.parentId !== "string") {
+        throw invalidEntry(filePath, lineNumber, "has invalid parentId");
+    }
+    if (typeof parsed.timestamp !== "string" || !parsed.timestamp) {
+        throw invalidEntry(filePath, lineNumber, "is missing timestamp");
+    }
+    if (parsed.type === "leaf" && parsed.targetId !== null && typeof parsed.targetId !== "string") {
+        throw invalidEntry(filePath, lineNumber, "has invalid targetId");
+    }
+    return parsed;
+}
+function leafIdAfterEntry(entry) {
+    return entry.type === "leaf" ? entry.targetId : entry.id;
+}
+function headerToSessionMetadata(header, path) {
+    return {
+        id: header.id,
+        createdAt: header.timestamp,
+        cwd: header.cwd,
+        path,
+        parentSessionPath: header.parentSession,
+    };
+}
+export async function loadJsonlSessionMetadata(fs, filePath) {
+    const lines = getFileSystemResultOrThrow(await fs.readTextLines(filePath, { maxLines: 1 }), `Failed to read session header ${filePath}`);
+    const line = lines[0];
+    if (line?.trim())
+        return headerToSessionMetadata(parseHeaderLine(line, filePath), filePath);
+    throw invalidSession(filePath, "missing session header");
+}
+async function loadJsonlStorage(fs, filePath) {
+    const content = getFileSystemResultOrThrow(await fs.readTextFile(filePath), `Failed to read session ${filePath}`);
+    const lines = content.split("\n").filter((line) => line.trim());
+    if (lines.length === 0) {
+        throw invalidSession(filePath, "missing session header");
+    }
+    const header = parseHeaderLine(lines[0], filePath);
+    const entries = [];
+    let leafId = null;
+    for (let i = 1; i < lines.length; i++) {
+        const entry = parseEntryLine(lines[i], filePath, i + 1);
+        entries.push(entry);
+        leafId = leafIdAfterEntry(entry);
+    }
+    return { header, entries, leafId };
+}
+export class JsonlSessionStorage {
+    fs;
+    filePath;
+    metadata;
+    entries;
+    byId;
+    labelsById;
+    currentLeafId;
+    constructor(fs, filePath, header, entries, leafId) {
+        this.fs = fs;
+        this.filePath = filePath;
+        this.metadata = headerToSessionMetadata(header, this.filePath);
+        this.entries = entries;
+        this.byId = new Map(entries.map((entry) => [entry.id, entry]));
+        this.labelsById = buildLabelsById(entries);
+        this.currentLeafId = leafId;
+    }
+    static async open(fs, filePath) {
+        const loaded = await loadJsonlStorage(fs, filePath);
+        return new JsonlSessionStorage(fs, filePath, loaded.header, loaded.entries, loaded.leafId);
+    }
+    static async create(fs, filePath, options) {
+        const header = {
+            type: "session",
+            version: 3,
+            id: options.sessionId,
+            timestamp: new Date().toISOString(),
+            cwd: options.cwd,
+            parentSession: options.parentSessionPath,
+        };
+        getFileSystemResultOrThrow(await fs.writeFile(filePath, `${JSON.stringify(header)}\n`), `Failed to create session ${filePath}`);
+        return new JsonlSessionStorage(fs, filePath, header, [], null);
+    }
+    async getMetadata() {
+        return this.metadata;
+    }
+    async getLeafId() {
+        if (this.currentLeafId !== null && !this.byId.has(this.currentLeafId)) {
+            throw new SessionError("invalid_session", `Entry ${this.currentLeafId} not found`);
+        }
+        return this.currentLeafId;
+    }
+    async setLeafId(leafId) {
+        if (leafId !== null && !this.byId.has(leafId)) {
+            throw new SessionError("not_found", `Entry ${leafId} not found`);
+        }
+        const entry = {
+            type: "leaf",
+            id: generateEntryId(this.byId),
+            parentId: this.currentLeafId,
+            timestamp: new Date().toISOString(),
+            targetId: leafId,
+        };
+        getFileSystemResultOrThrow(await this.fs.appendFile(this.filePath, `${JSON.stringify(entry)}\n`), `Failed to append session leaf ${entry.id}`);
+        this.entries.push(entry);
+        this.byId.set(entry.id, entry);
+        this.currentLeafId = leafId;
+    }
+    async createEntryId() {
+        return generateEntryId(this.byId);
+    }
+    async appendEntry(entry) {
+        getFileSystemResultOrThrow(await this.fs.appendFile(this.filePath, `${JSON.stringify(entry)}\n`), `Failed to append session entry ${entry.id}`);
+        this.entries.push(entry);
+        this.byId.set(entry.id, entry);
+        updateLabelCache(this.labelsById, entry);
+        this.currentLeafId = leafIdAfterEntry(entry);
+    }
+    async getEntry(id) {
+        return this.byId.get(id);
+    }
+    async findEntries(type) {
+        return this.entries.filter((entry) => entry.type === type);
+    }
+    async getLabel(id) {
+        return this.labelsById.get(id);
+    }
+    async getPathToRoot(leafId) {
+        if (leafId === null)
+            return [];
+        const path = [];
+        let current = this.byId.get(leafId);
+        if (!current)
+            throw new SessionError("not_found", `Entry ${leafId} not found`);
+        while (current) {
+            path.unshift(current);
+            if (!current.parentId)
+                break;
+            const parent = this.byId.get(current.parentId);
+            if (!parent)
+                throw new SessionError("invalid_session", `Entry ${current.parentId} not found`);
+            current = parent;
+        }
+        return path;
+    }
+    async getEntries() {
+        return [...this.entries];
+    }
+}

package/dist/pi/agent-core/harness/session/memory-repo.js

@@ -0,0 +1,41 @@
+import { SessionError } from "../types.js";
+import { InMemorySessionStorage } from "./memory-storage.js";
+import { createSessionId, createTimestamp, getEntriesToFork, toSession } from "./repo-utils.js";
+export class InMemorySessionRepo {
+    sessions = new Map();
+    async create(options = {}) {
+        const metadata = {
+            id: options.id ?? createSessionId(),
+            createdAt: createTimestamp(),
+        };
+        const storage = new InMemorySessionStorage({ metadata });
+        const session = toSession(storage);
+        this.sessions.set(metadata.id, session);
+        return session;
+    }
+    async open(metadata) {
+        const session = this.sessions.get(metadata.id);
+        if (!session) {
+            throw new SessionError("not_found", `Session not found: ${metadata.id}`);
+        }
+        return session;
+    }
+    async list() {
+        return Promise.all([...this.sessions.values()].map((session) => session.getMetadata()));
+    }
+    async delete(metadata) {
+        this.sessions.delete(metadata.id);
+    }
+    async fork(sourceMetadata, options) {
+        const source = await this.open(sourceMetadata);
+        const forkedEntries = await getEntriesToFork(source.getStorage(), options);
+        const metadata = {
+            id: options.id ?? createSessionId(),
+            createdAt: createTimestamp(),
+        };
+        const storage = new InMemorySessionStorage({ metadata, entries: forkedEntries });
+        const session = toSession(storage);
+        this.sessions.set(metadata.id, session);
+        return session;
+    }
+}