@cogineai/dearharness 0.1.0

package/dist/runtime/assembly.js

@@ -0,0 +1,54 @@
+import { loadExtensions } from '../extensions/loader.js';
+import { buildInstructionMessages, loadWorkspaceInstructionFiles } from '../instructions/builder.js';
+import { BASE_SYSTEM_PROMPT } from '../prompt/system.js';
+import { loadSkills, mergeSkillNames } from '../skills/loader.js';
+import { loadWorkspaceConfig } from '../workspace/config.js';
+const INSTRUCTION_LAYERS = new Set(['core', 'workspace', 'skill', 'extension']);
+function validateExtensionMessages(extensionName, value) {
+    if (!Array.isArray(value)) {
+        throw new Error(`Extension ${extensionName} instruction source returned invalid value, expected array`);
+    }
+    value.forEach((message, index) => {
+        if (!message ||
+            typeof message !== 'object' ||
+            message.role !== 'system' ||
+            typeof message.content !== 'string' ||
+            typeof message.source !== 'string' ||
+            !INSTRUCTION_LAYERS.has(message.layer)) {
+            throw new Error(`Extension ${extensionName} instruction source returned invalid message at index ${index}`);
+        }
+    });
+    return value;
+}
+export async function createRuntimeAssembly({ cwd, session, policyMode, cliSkillNames }) {
+    const workspaceConfig = await loadWorkspaceConfig(cwd);
+    const skillNames = mergeSkillNames(workspaceConfig.defaultSkills, cliSkillNames);
+    const extensions = await loadExtensions(cwd, workspaceConfig.extensions);
+    const skills = await loadSkills(cwd, skillNames);
+    const workspaceInstructions = await loadWorkspaceInstructionFiles(cwd, workspaceConfig.instructionFiles);
+    return {
+        workspaceConfig,
+        skillNames,
+        extensionNames: extensions.map((extension) => extension.name),
+        hooks: extensions.flatMap((extension) => extension.hooks ?? []),
+        session,
+        async instructions(currentSession) {
+            const extensionMessages = (await Promise.all(extensions.flatMap((extension) => (extension.instructionSources ?? []).map(async (source) => {
+                try {
+                    const messages = await source({ cwd, session: currentSession, policyMode });
+                    return validateExtensionMessages(extension.name, messages);
+                }
+                catch (error) {
+                    throw new Error(`Extension ${extension.name} instruction source failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            })))).flat();
+            return buildInstructionMessages({
+                cwd,
+                basePrompt: BASE_SYSTEM_PROMPT,
+                workspaceInstructions,
+                skills: skills.map((skill) => ({ name: skill.name, prompt: skill.prompt })),
+                extensionMessages
+            });
+        }
+    };
+}

package/dist/runtime/events.js

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

package/dist/runtime/hooks.js

@@ -0,0 +1,13 @@
+export async function runHooks(hooks, name, ...args) {
+    for (const hook of hooks) {
+        const fn = hook[name];
+        if (fn) {
+            try {
+                await fn(...args);
+            }
+            catch (error) {
+                console.error(`hook ${String(name)} failed:`, error);
+            }
+        }
+    }
+}

package/dist/runtime/runner.js

@@ -0,0 +1,193 @@
+import { DEFAULT_POLICY_MODE, MAX_LOOPS } from '../config.js';
+import { createPolicyEngine } from '../policy/engine.js';
+import { parseModelAction } from '../protocol/actions.js';
+import { appendRecord, makeId, nowIso, saveSession } from '../session/store.js';
+import { createToolRegistry } from '../tools/registry.js';
+import { runHooks } from './hooks.js';
+function buildChatMessages(session, instructions) {
+    return [
+        ...instructions.map(({ role, content }) => ({ role, content })),
+        ...session.records.map((record) => record.kind === 'tool'
+            ? { role: 'user', content: record.content }
+            : { role: record.role, content: record.content })
+    ];
+}
+export function createRunner({ model, registry = createToolRegistry(), hooks = [], policy = createPolicyEngine({ mode: DEFAULT_POLICY_MODE }), instructions = async () => [], onEvent = async () => undefined }) {
+    return {
+        async runTurn(session, userInput) {
+            const cwd = session.cwd;
+            try {
+                session.lifecycle.status = 'running';
+                session.lifecycle.turn += 1;
+                session.lifecycle.lastUserInputAt = nowIso();
+                await appendRecord(cwd, session, {
+                    id: makeId('usr'),
+                    ts: nowIso(),
+                    kind: 'user',
+                    role: 'user',
+                    content: userInput
+                });
+                await runHooks(hooks, 'beforeTurn', session, userInput);
+                for (let i = 0; i < MAX_LOOPS; i += 1) {
+                    let chunks = 0;
+                    let chars = 0;
+                    let activeProvider = null;
+                    let activeModel = null;
+                    let sawModelStart = false;
+                    let sawModelEnd = false;
+                    let sawModelError = false;
+                    let completion;
+                    try {
+                        completion = await model.complete(buildChatMessages(session, await instructions(session)), {
+                            async onEvent(event) {
+                                if (event.type === 'start') {
+                                    activeProvider = event.provider;
+                                    activeModel = event.model;
+                                    sawModelStart = true;
+                                    await onEvent({
+                                        type: 'model-start',
+                                        provider: event.provider,
+                                        model: event.model,
+                                        streaming: event.streaming
+                                    });
+                                }
+                                else if (event.type === 'text-delta') {
+                                    chunks += 1;
+                                    chars += event.text.length;
+                                    await onEvent({ type: 'model-progress', chunks, chars });
+                                }
+                                else if (event.type === 'end') {
+                                    if (activeProvider && activeModel) {
+                                        sawModelEnd = true;
+                                        await onEvent({ type: 'model-end', provider: activeProvider, model: activeModel });
+                                    }
+                                }
+                                else if (event.type === 'error') {
+                                    sawModelError = true;
+                                    await onEvent({ type: 'error', stage: 'model', message: event.message });
+                                }
+                            }
+                        });
+                    }
+                    catch (error) {
+                        if (!sawModelError) {
+                            await onEvent({
+                                type: 'error',
+                                stage: 'model',
+                                message: error instanceof Error ? error.message : String(error)
+                            });
+                        }
+                        throw error;
+                    }
+                    if (!sawModelStart) {
+                        await onEvent({
+                            type: 'model-start',
+                            provider: completion.provider,
+                            model: completion.model,
+                            streaming: false
+                        });
+                    }
+                    if (!sawModelEnd) {
+                        await onEvent({ type: 'model-end', provider: completion.provider, model: completion.model });
+                    }
+                    const rawContent = completion.content;
+                    let action;
+                    try {
+                        action = parseModelAction(rawContent);
+                    }
+                    catch (error) {
+                        await onEvent({
+                            type: 'error',
+                            stage: 'protocol',
+                            message: error instanceof Error ? error.message : String(error)
+                        });
+                        throw error;
+                    }
+                    session.lifecycle.lastAssistantOutputAt = nowIso();
+                    await appendRecord(cwd, session, {
+                        id: makeId('ast'),
+                        ts: nowIso(),
+                        kind: 'assistant',
+                        role: 'assistant',
+                        content: rawContent,
+                        action
+                    });
+                    await runHooks(hooks, 'afterAssistantAction', session, action, rawContent);
+                    if ('message' in action) {
+                        const finalMessage = action.message.trim() || '(no content)';
+                        await runHooks(hooks, 'afterTurn', session, finalMessage);
+                        await onEvent({ type: 'final', message: finalMessage });
+                        return finalMessage;
+                    }
+                    const { definition } = registry.resolve(action);
+                    await onEvent({ type: 'tool-start', tool: definition.name, preview: rawContent.slice(0, 120) });
+                    let result = null;
+                    let authorization = null;
+                    try {
+                        authorization = await policy.authorize(definition);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        result = {
+                            tool: definition.name,
+                            status: 'error',
+                            content: `TOOL_RESULT ${definition.name} ERROR\npolicy=${policy.mode}\n${message}`,
+                            meta: {
+                                policy: policy.mode,
+                                error: error instanceof Error ? (error.stack ?? error.message) : message
+                            }
+                        };
+                    }
+                    if (result === null && authorization !== null && !authorization.allowed) {
+                        result = {
+                            tool: definition.name,
+                            status: 'error',
+                            content: `TOOL_RESULT ${definition.name} ERROR\npolicy=${policy.mode}\n${authorization.reason}`,
+                            meta: {
+                                policy: policy.mode,
+                                reason: authorization.reason
+                            }
+                        };
+                    }
+                    else if (result === null && authorization !== null) {
+                        await runHooks(hooks, 'beforeTool', session, action);
+                        try {
+                            result = await definition.execute(action, { cwd, session });
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            result = {
+                                tool: definition.name,
+                                status: 'error',
+                                content: `TOOL_RESULT ${definition.name} ERROR\n${message}`,
+                                meta: {
+                                    error: error instanceof Error ? (error.stack ?? error.message) : message
+                                }
+                            };
+                        }
+                    }
+                    if (result === null) {
+                        throw new Error(`No tool result produced for ${definition.name}`);
+                    }
+                    await appendRecord(cwd, session, {
+                        id: makeId('tool'),
+                        ts: nowIso(),
+                        kind: 'tool',
+                        role: 'user',
+                        tool: result.tool,
+                        status: result.status,
+                        content: result.content,
+                        meta: result.meta
+                    });
+                    await runHooks(hooks, 'afterTool', session, result);
+                    await onEvent({ type: 'tool-end', tool: result.tool, status: result.status });
+                }
+                throw new Error('Exceeded action loop limit');
+            }
+            finally {
+                session.lifecycle.status = 'idle';
+                await saveSession(cwd, session);
+            }
+        }
+    };
+}

package/dist/session/store.js

@@ -0,0 +1,198 @@
+import crypto from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { APP_DIR, DEFAULT_MODEL_BASE_URL, DEFAULT_MODEL_PROVIDER, OLLAMA_DEFAULT_BASE_URL, SESSION_FILE, SESSION_VERSION } from '../config.js';
+import { isProviderName } from '../model/registry.js';
+function isSessionRecord(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (typeof record.id !== 'string' || typeof record.ts !== 'string' || typeof record.kind !== 'string' || typeof record.role !== 'string') {
+        return false;
+    }
+    if (record.kind === 'system' || record.kind === 'user') {
+        return typeof record.content === 'string';
+    }
+    if (record.kind === 'assistant') {
+        return record.role === 'assistant' && typeof record.content === 'string' && 'action' in record;
+    }
+    if (record.kind === 'tool') {
+        return (record.role === 'user' &&
+            typeof record.tool === 'string' &&
+            (record.status === 'ok' || record.status === 'error') &&
+            typeof record.content === 'string');
+    }
+    return false;
+}
+function defaultSessionModel() {
+    return {
+        provider: 'ollama',
+        model: 'auto',
+        baseUrl: OLLAMA_DEFAULT_BASE_URL
+    };
+}
+function isSessionModelLike(value) {
+    if (typeof value === 'string') {
+        return true;
+    }
+    const model = value;
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof model.provider === 'string' &&
+        isProviderName(model.provider) &&
+        typeof model.model === 'string' &&
+        (model.baseUrl === undefined || typeof model.baseUrl === 'string'));
+}
+function normalizeSessionModel(value) {
+    if (typeof value === 'string') {
+        return {
+            provider: DEFAULT_MODEL_PROVIDER,
+            model: value,
+            baseUrl: DEFAULT_MODEL_BASE_URL
+        };
+    }
+    if (isSessionModelLike(value) && typeof value !== 'string') {
+        return value;
+    }
+    return defaultSessionModel();
+}
+export function sessionPath(cwd) {
+    return path.join(cwd, APP_DIR, SESSION_FILE);
+}
+export function makeId(prefix) {
+    return `${prefix}_${crypto.randomUUID()}`;
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function createSession(cwd) {
+    const now = nowIso();
+    return {
+        version: SESSION_VERSION,
+        app: 'cliq',
+        model: defaultSessionModel(),
+        cwd,
+        createdAt: now,
+        updatedAt: now,
+        lifecycle: { status: 'idle', turn: 0 },
+        records: []
+    };
+}
+function isSession(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.version === 'number' &&
+        value.app === 'cliq' &&
+        isSessionModelLike(value.model) &&
+        typeof value.cwd === 'string' &&
+        typeof value.createdAt === 'string' &&
+        typeof value.updatedAt === 'string' &&
+        !!value.lifecycle &&
+        typeof value.lifecycle === 'object' &&
+        (value.lifecycle.status === 'idle' || value.lifecycle.status === 'running') &&
+        typeof value.lifecycle.turn === 'number' &&
+        Array.isArray(value.records) &&
+        value.records.every((record) => isSessionRecord(record)));
+}
+function stripSeededSystemPrompt(records, sourceVersion = 0) {
+    if (sourceVersion > 2) {
+        return records;
+    }
+    return records.filter((record, index) => {
+        return !(index === 0 &&
+            record.kind === 'system' &&
+            record.role === 'system');
+    });
+}
+function normalizeSession(session) {
+    const records = stripSeededSystemPrompt(session.records, session.version);
+    const version = Math.max(session.version, SESSION_VERSION);
+    const rawModel = session.model;
+    const model = normalizeSessionModel(rawModel);
+    const modelChanged = model !== rawModel;
+    if (version === session.version && records.length === session.records.length && !modelChanged) {
+        return session;
+    }
+    return {
+        ...session,
+        version,
+        model,
+        records
+    };
+}
+function migrateLegacySession(cwd, legacy) {
+    const session = createSession(cwd);
+    session.createdAt = legacy.createdAt ?? session.createdAt;
+    session.updatedAt = legacy.updatedAt ?? session.updatedAt;
+    session.records = [];
+    for (const message of legacy.messages ?? []) {
+        const ts = nowIso();
+        if (message.role === 'system' && typeof message.content === 'string') {
+            session.records.push({ id: makeId('sys'), ts, kind: 'system', role: 'system', content: message.content });
+        }
+        else if (message.role === 'user' && typeof message.content === 'string') {
+            session.records.push({ id: makeId('usr'), ts, kind: 'user', role: 'user', content: message.content });
+        }
+        else if (message.role === 'assistant') {
+            session.records.push({
+                id: makeId('ast'),
+                ts,
+                kind: 'assistant',
+                role: 'assistant',
+                content: message.content ?? '',
+                action: null
+            });
+        }
+        else if (message.role === 'tool') {
+            session.records.push({
+                id: makeId('tool'),
+                ts,
+                kind: 'tool',
+                role: 'user',
+                tool: message.name === 'edit' ? 'edit' : 'bash',
+                // Older sessions may not store tool status, so default only when absent.
+                status: message.status ?? 'ok',
+                content: message.content ?? ''
+            });
+        }
+    }
+    session.records = stripSeededSystemPrompt(session.records);
+    return session;
+}
+export async function saveSession(cwd, session) {
+    session.updatedAt = nowIso();
+    const target = sessionPath(cwd);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, JSON.stringify(session, null, 2));
+}
+export async function appendRecord(cwd, session, record) {
+    session.records.push(record);
+    await saveSession(cwd, session);
+}
+export async function ensureSession(cwd) {
+    const target = sessionPath(cwd);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    try {
+        const raw = JSON.parse(await fs.readFile(target, 'utf8'));
+        if (isSession(raw)) {
+            const normalized = normalizeSession(raw);
+            if (normalized !== raw) {
+                await saveSession(cwd, normalized);
+            }
+            return normalized;
+        }
+        const migrated = migrateLegacySession(cwd, raw);
+        await saveSession(cwd, migrated);
+        return migrated;
+    }
+    catch {
+        const session = createSession(cwd);
+        await saveSession(cwd, session);
+        return session;
+    }
+}
+export async function ensureFresh(cwd) {
+    await fs.rm(path.join(cwd, APP_DIR), { recursive: true, force: true });
+    return ensureSession(cwd);
+}

package/dist/session/types.js

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

package/dist/skills/loader.js

@@ -0,0 +1,51 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { APP_DIR } from '../config.js';
+import { resolveWorkspacePath } from '../tools/path.js';
+export function mergeSkillNames(defaultSkills, cliSkills) {
+    return [...new Set([...defaultSkills, ...cliSkills])];
+}
+function isValidSkillName(name) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+function parseSkillMarkdown(raw) {
+    const match = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n+([\s\S]*)$/);
+    if (!match) {
+        throw new Error('Skill file must begin with frontmatter');
+    }
+    const headers = Object.fromEntries(match[1]
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => {
+        const [key, ...rest] = line.split(':');
+        return [key.trim(), rest.join(':').trim()];
+    }));
+    if (!headers.name) {
+        throw new Error('Skill file must declare a name');
+    }
+    const prompt = match[2].trim();
+    if (!prompt) {
+        throw new Error('Skill prompt body must not be empty');
+    }
+    return {
+        name: headers.name,
+        description: headers.description ?? null,
+        prompt
+    };
+}
+export async function loadSkills(cwd, names) {
+    const loaded = [];
+    for (const name of names) {
+        if (!isValidSkillName(name)) {
+            throw new Error(`Invalid skill name: ${name}`);
+        }
+        const { targetRealPath } = await resolveWorkspacePath(cwd, path.join(APP_DIR, 'skills', name, 'SKILL.md'));
+        const raw = await fs.readFile(targetRealPath, 'utf8');
+        const skill = parseSkillMarkdown(raw);
+        if (skill.name !== name) {
+            throw new Error(`Skill ${name} must declare matching frontmatter name`);
+        }
+        loaded.push(skill);
+    }
+    return loaded;
+}

package/dist/skills/types.js

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

package/dist/tools/bash.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import { BASH_TIMEOUT_MS, MAX_OUTPUT } from '../config.js';
+function clip(text) {
+    return text.length <= MAX_OUTPUT ? text : text.slice(-MAX_OUTPUT);
+}
+export const bashTool = {
+    name: 'bash',
+    access: 'exec',
+    supports(action) {
+        return typeof action.bash === 'string';
+    },
+    async execute(action, context) {
+        return await new Promise((resolve) => {
+            const child = spawn('bash', ['-lc', action.bash], { cwd: context.cwd, env: process.env });
+            let out = '';
+            let timedOut = false;
+            let settled = false;
+            let killTimer;
+            const finish = (result) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                if (killTimer) {
+                    clearTimeout(killTimer);
+                }
+                resolve(result);
+            };
+            const onData = (chunk) => {
+                out += chunk.toString();
+                out = clip(out);
+            };
+            child.stdout?.on('data', onData);
+            child.stderr?.on('data', onData);
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                killTimer = setTimeout(() => {
+                    if (!settled) {
+                        child.kill('SIGKILL');
+                    }
+                }, 250);
+                out = clip(`${out}\n[process timed out after ${BASH_TIMEOUT_MS}ms]`);
+            }, BASH_TIMEOUT_MS);
+            child.on('error', (error) => {
+                finish({
+                    tool: 'bash',
+                    status: 'error',
+                    meta: { exit: null, signal: error.code ?? 'error', timed_out: false },
+                    content: [`TOOL_RESULT bash ERROR`, `$ ${action.bash}`, `(exit=null signal=${error.code ?? 'error'})`, error.message]
+                        .filter(Boolean)
+                        .join('\n')
+                        .trim()
+                });
+            });
+            child.on('close', (code, signal) => {
+                const status = code === 0 && !timedOut ? 'ok' : 'error';
+                finish({
+                    tool: 'bash',
+                    status,
+                    meta: { exit: code ?? null, signal: signal ?? 'none', timed_out: timedOut },
+                    content: [`TOOL_RESULT bash ${status.toUpperCase()}`, `$ ${action.bash}`, `(exit=${code ?? 'null'} signal=${signal ?? 'none'})`, out]
+                        .filter(Boolean)
+                        .join('\n')
+                        .trim()
+                });
+            });
+        });
+    }
+};

package/dist/tools/edit.js

@@ -0,0 +1,61 @@
+import { promises as fs } from 'node:fs';
+import { resolveWorkspacePath, WORKSPACE_PATH_ERROR } from './path.js';
+export const editTool = {
+    name: 'edit',
+    access: 'write',
+    supports(action) {
+        return typeof action.edit === 'object' && !!action.edit;
+    },
+    async execute(action, context) {
+        let targetRealPath;
+        let relativePath;
+        try {
+            ({ targetRealPath, relativePath } = await resolveWorkspacePath(context.cwd, action.edit.path));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const displayError = message === WORKSPACE_PATH_ERROR
+                ? 'edit.path must be a workspace-relative path inside the workspace'
+                : message;
+            const meta = { path: action.edit.path, error: displayError };
+            return {
+                tool: 'edit',
+                status: 'error',
+                meta,
+                content: `TOOL_RESULT edit ERROR\npath=${action.edit.path}\n${displayError}`
+            };
+        }
+        try {
+            const current = await fs.readFile(targetRealPath, 'utf8');
+            const matches = current.split(action.edit.old_text).length - 1;
+            if (matches !== 1) {
+                const error = `expected old_text to match exactly once, but matched ${matches} times`;
+                const meta = { path: relativePath, matches, error };
+                return {
+                    tool: 'edit',
+                    status: 'error',
+                    meta,
+                    content: `TOOL_RESULT edit ERROR\npath=${relativePath}\n${error}`
+                };
+            }
+            const meta = { path: relativePath };
+            await fs.writeFile(targetRealPath, current.replace(action.edit.old_text, action.edit.new_text), 'utf8');
+            return {
+                tool: 'edit',
+                status: 'ok',
+                meta,
+                content: `TOOL_RESULT edit OK\npath=${relativePath}\nreplaced exact text span successfully`
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const meta = { path: relativePath, error: message };
+            return {
+                tool: 'edit',
+                status: 'error',
+                meta,
+                content: `TOOL_RESULT edit ERROR\npath=${relativePath}\n${message}`
+            };
+        }
+    }
+};