@theihtisham/agent-shadow-brain 7.1.0 → 7.1.4

package/dist/brain/project-kit.js

@@ -0,0 +1,255 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { inspectProject } from './project-kit-inspection.js';
+import { ensureProjectDirectory, projectLocalPath, projectRoot, ProjectKitError, readProjectFile } from './project-kit-paths.js';
+import { WORKFLOW_TARGETS } from './workflow-skills.js';
+import { matchesFileIdentity } from './file-identity.js';
+export { inspectProject } from './project-kit-inspection.js';
+export { ensureProjectDirectory, projectLocalPath, projectRoot, ProjectKitError } from './project-kit-paths.js';
+const MAX_INPUT = 8000;
+const MAX_SKILL = 64 * 1024;
+const RECEIPT_DIR = '.shadow-brain/project-kit-skills';
+const HASH_PATTERN = /^[a-f0-9]{64}$/u;
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u;
+function sha(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function inputText(value, label) {
+    if (typeof value !== 'string' || value.length > MAX_INPUT || CONTROL.test(value)) {
+        throw new TypeError(label + ' must be text of at most 8000 characters without control codes.');
+    }
+    return value.replace(/\r\n?/g, '\n').trim();
+}
+function inputs(params, project) {
+    if (!params || typeof params !== 'object' || Array.isArray(params) ||
+        Object.keys(params).some(key => !['requirement', 'target', 'name', 'knowledge'].includes(key))) {
+        throw new TypeError('Provide a requirement, target, and optional name and knowledge.');
+    }
+    const requirement = inputText(params.requirement, 'Requirement');
+    if (!requirement)
+        throw new TypeError('Provide a nonempty requirement.');
+    if (typeof params.target !== 'string' || !Object.hasOwn(WORKFLOW_TARGETS, params.target))
+        throw new TypeError('Choose a supported skill target.');
+    const task = requirement.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 46).replace(/-$/g, '') || 'project-task';
+    const name = params.name ?? task + '-' + sha(project.projectId + '\0' + requirement).slice(0, 10);
+    if (typeof name !== 'string' || name.length > 63 || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
+        throw new TypeError('Skill name must be 1 to 63 lowercase letters, digits, or hyphen-separated words.');
+    }
+    const raw = params.knowledge ?? '';
+    if (Array.isArray(raw) && raw.length > 100)
+        throw new TypeError('Provide at most 100 knowledge notes.');
+    const knowledge = Array.isArray(raw) ? raw.map(note => inputText(note, 'Knowledge')).filter(Boolean).join('\n\n') : inputText(raw, 'Knowledge');
+    if (knowledge.length > MAX_INPUT)
+        throw new TypeError('Combined knowledge must be at most 8000 characters.');
+    return { requirement, target: params.target, name, knowledge };
+}
+function quote(text) {
+    return text.split('\n').map(line => '> ' + line).join('\n');
+}
+function inline(value) {
+    return value.replace(/[\\`*_{}\[\]()<>#!|~]/g, '\\$&');
+}
+function renderSkill(profile, selected) {
+    const { requirement, name, knowledge } = selected;
+    const trigger = requirement.replace(/\s+/g, ' ').slice(0, 150);
+    const rows = [
+        '---',
+        'name: ' + JSON.stringify(name),
+        'description: ' + JSON.stringify('Use for this project task: ' + trigger),
+        '---',
+        '',
+        '# ' + name,
+        '',
+        'Use this skill within the selected project. Follow current user instructions and applicable project rules first. Recheck saved observations when the project changes.',
+        '',
+        '## Requirement supplied by the user',
+        '',
+        quote(requirement),
+        ...(knowledge ? ['', '## Project knowledge supplied by the user', '', quote(knowledge)] : []),
+        '',
+        '## Observed project markers',
+        '',
+        ...(profile.evidence.length ? profile.evidence.slice(0, 16).map(item => '- ' + inline(item.path) + ' indicates ' + item.signals.map(inline).join(', ') + '.') :
+            ['- The bounded inspection found no recognized project markers. Confirm the stack before choosing a verification command.']),
+        '',
+        '## Work and verify',
+        '',
+        '1. Confirm the requested result, the affected project files, and any current constraints.',
+        '2. Use the supplied requirement and project knowledge as task context. Verify evidence before relying on it.',
+        '3. Make the requested change and inspect it through the normal project entry point.',
+        '4. Run the relevant declared checks after confirming they still apply and review the actual result.',
+        '',
+        ...(profile.checks.length ? ['Declared checks observed in project manifests. Use each check from the directory containing its source.',
+            ...profile.checks.slice(0, 12).map(item => '- ' + inline(item.label) + ' uses `' + item.command + '` from ' + inline(item.source) + '.')] :
+            ['The bounded inspection found no recognized declared checks. Use the project’s current verification procedure.']),
+        '',
+        'If the project exposes `project_feedback`, report a memory ID and observed outcome only when a check or the user’s feedback supports the rating. Describe the evidence and uncertainty. Retrieval rank and successful tool execution alone do not establish a useful or correct memory.',
+        '',
+    ];
+    return rows.join('\n');
+}
+function receiptPath(relative) {
+    return RECEIPT_DIR + '/' + sha(relative) + '.json';
+}
+function readReceipt(profile, relative) {
+    const bytes = readProjectFile(profile.root, receiptPath(relative), 4096);
+    if (!bytes)
+        return undefined;
+    try {
+        const receipt = JSON.parse(bytes.toString('utf8'));
+        if (receipt?.schemaVersion === 1 && receipt.projectId === profile.projectId && receipt.relativePath === relative && HASH_PATTERN.test(receipt.sha256)) {
+            return { receipt, bytes };
+        }
+    }
+    catch { /* Invalid ownership data cannot establish ownership. */ }
+    throw new ProjectKitError('PROJECT_KIT_CONFLICT', 'The project skill ownership receipt is invalid.');
+}
+function destinationState(profile, relativePath, content) {
+    const file = { relativePath, content };
+    try {
+        const filename = projectLocalPath(profile.root, relativePath);
+        const existing = fs.lstatSync(filename, { throwIfNoEntry: false });
+        const ownership = readReceipt(profile, relativePath);
+        if (!existing && !ownership)
+            return { ...file, status: 'create' };
+        if (!existing || !ownership) {
+            return { ...file, status: 'conflict', reason: existing ? 'An existing file is outside Project Kit ownership.' : 'The previously owned skill file is missing.' };
+        }
+        const bytes = readProjectFile(profile.root, relativePath, MAX_SKILL);
+        if (!bytes)
+            return { ...file, status: 'conflict', reason: 'The skill file changed during preview.' };
+        const existingHash = sha(bytes);
+        if (existingHash !== ownership.receipt.sha256)
+            return { ...file, existingHash, status: 'conflict', reason: 'The owned skill was edited after its last application.' };
+        return { ...file, existingHash, status: existingHash === sha(content) ? 'unchanged' : 'update' };
+    }
+    catch (error) {
+        if (!(error instanceof ProjectKitError))
+            throw error;
+        return { ...file, status: 'conflict', reason: error.message };
+    }
+}
+/** Produce a read-only, root-bound preview. Existing unowned skill bytes are never read. */
+export function planProjectSkill(root, params) {
+    const profile = inspectProject(root);
+    const selected = inputs(params, profile);
+    const relative = WORKFLOW_TARGETS[selected.target].skillRoot + '/' + selected.name + '/SKILL.md';
+    const content = renderSkill(profile, selected);
+    const file = destinationState(profile, relative, content);
+    const { projectId, root: projectDirectory, stack, packageManagers, evidence, checks } = profile;
+    const planHash = sha(JSON.stringify({ schemaVersion: 1, projectId, root: projectDirectory, stack, packageManagers, evidence, checks, ...selected, file }));
+    return { projectId: profile.projectId, profile, requirement: selected.requirement, target: selected.target,
+        name: selected.name, files: [file], planHash, warnings: [...profile.warnings] };
+}
+function replaceProjectFile(root, relative, content, expectedHash) {
+    const filename = projectLocalPath(root, relative);
+    const temporary = filename + '.' + randomUUID() + '.tmp';
+    const fd = fs.openSync(temporary, 'wx', 0o600);
+    try {
+        try {
+            fs.writeFileSync(fd, content);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        projectLocalPath(root, relative);
+        if (expectedHash) {
+            const before = readProjectFile(root, relative, MAX_SKILL);
+            if (!before || sha(before) !== expectedHash)
+                throw new ProjectKitError('PROJECT_KIT_STALE_PLAN', 'A managed file changed during application.');
+            fs.renameSync(temporary, filename);
+        }
+        else {
+            // Linking a prepared sibling creates the destination exclusively without clobbering an intervening file.
+            fs.linkSync(temporary, filename);
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+function assertPlan(plan, expectedPlanHash) {
+    if (plan.files[0].status === 'conflict') {
+        throw new ProjectKitError('PROJECT_KIT_CONFLICT', plan.files[0].reason ?? 'The skill has a destination conflict.');
+    }
+    if (plan.planHash !== expectedPlanHash) {
+        throw new ProjectKitError('PROJECT_KIT_STALE_PLAN', 'The project skill preview changed. Create a new preview before applying.');
+    }
+}
+/** Rebuild the reviewed preview under a project-local write lock, then save only its managed skill and receipt. */
+export async function applyProjectSkill(root, params, expectedPlanHash) {
+    if (typeof expectedPlanHash !== 'string' || !HASH_PATTERN.test(expectedPlanHash))
+        throw new TypeError('A current project skill plan hash is required.');
+    const initial = planProjectSkill(root, params);
+    assertPlan(initial, expectedPlanHash);
+    const canonical = projectRoot(initial.profile.root);
+    const result = (status) => ({
+        projectId: initial.projectId, planHash: initial.planHash, files: [{ relativePath: initial.files[0].relativePath, status }], warnings: initial.warnings,
+    });
+    if (initial.files[0].status === 'unchanged')
+        return result('unchanged');
+    const lockDirectory = ensureProjectDirectory(canonical, RECEIPT_DIR);
+    const lock = path.join(lockDirectory, 'write.lock');
+    let fd;
+    try {
+        fd = fs.openSync(lock, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new ProjectKitError('PROJECT_KIT_CONFLICT', 'Another Project Kit write is in progress.');
+        throw new ProjectKitError('PROJECT_KIT_WRITE_FAILED', 'Could not acquire the project skill write lock.');
+    }
+    const owner = fs.fstatSync(fd, { bigint: true });
+    try {
+        const plan = planProjectSkill(canonical, params);
+        assertPlan(plan, expectedPlanHash);
+        const file = plan.files[0];
+        ensureProjectDirectory(canonical, path.posix.dirname(file.relativePath));
+        const prior = file.existingHash ? readProjectFile(canonical, file.relativePath, MAX_SKILL) : undefined;
+        const receipt = readReceipt(plan.profile, file.relativePath);
+        if (file.existingHash !== receipt?.receipt.sha256) {
+            throw new ProjectKitError('PROJECT_KIT_STALE_PLAN', 'The project skill ownership changed during application.');
+        }
+        const newHash = sha(file.content);
+        const next = { schemaVersion: 1, projectId: plan.projectId, relativePath: file.relativePath, sha256: newHash };
+        try {
+            replaceProjectFile(canonical, file.relativePath, file.content, file.existingHash);
+            try {
+                replaceProjectFile(canonical, receiptPath(file.relativePath), JSON.stringify(next) + '\n', receipt ? sha(receipt.bytes) : undefined);
+            }
+            catch (error) {
+                const written = readProjectFile(canonical, file.relativePath, MAX_SKILL);
+                if (written && sha(written) === newHash) {
+                    if (prior)
+                        replaceProjectFile(canonical, file.relativePath, prior, newHash);
+                    else
+                        fs.unlinkSync(projectLocalPath(canonical, file.relativePath));
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error instanceof ProjectKitError)
+                throw error;
+            throw new ProjectKitError('PROJECT_KIT_WRITE_FAILED', 'Could not save the project skill and ownership receipt.');
+        }
+        return result(file.status === 'create' ? 'created' : 'updated');
+    }
+    finally {
+        fs.closeSync(fd);
+        const current = fs.lstatSync(lock, { throwIfNoEntry: false, bigint: true });
+        if (matchesFileIdentity(lock, owner, current))
+            fs.unlinkSync(lock);
+    }
+}
+//# sourceMappingURL=project-kit.js.map

package/dist/brain/project-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-kit.js","sourceRoot":"","sources":["../../src/brain/project-kit.ts"],"names":[],"mappings":"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"}

package/dist/brain/project-memory.d.ts

@@ -0,0 +1,38 @@
+import { GlobalBrain } from './global-brain.js';
+export interface ProjectKnowledgeInput {
+    title: string;
+    content: string;
+    category?: string;
+    source?: string;
+}
+/** Explicit project-local paths only; never consults the default global store. */
+export declare function projectStorage(directory: string): {
+    root: string;
+    projectId: string;
+    projectName: string;
+    storagePath: string;
+    settingsPath: string;
+    annotationsPath: string;
+    journalPath: string;
+    feedbackPath: string;
+};
+/** Identify an explicit project store even when Windows launch paths use different spellings. */
+export declare function resolveProjectStore(directory: string, dbPath: string | undefined): ReturnType<typeof projectStorage> | undefined;
+export declare function requireProjectStore(directory: string, brain: GlobalBrain): {
+    root: string;
+    projectId: string;
+    projectName: string;
+    storagePath: string;
+    settingsPath: string;
+    annotationsPath: string;
+    journalPath: string;
+    feedbackPath: string;
+};
+export declare function parseProjectKnowledge(input: unknown): ProjectKnowledgeInput;
+/** Only explicit user knowledge. Source references are labels and are never opened. */
+export declare function addProjectKnowledge(directory: string, brain: GlobalBrain, input: unknown): Promise<{
+    ok: true;
+    memoryId: string;
+    projectId: string;
+}>;
+//# sourceMappingURL=project-memory.d.ts.map

package/dist/brain/project-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-memory.d.ts","sourceRoot":"","sources":["../../src/brain/project-memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,MAAM,WAAW,qBAAqB;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE;AAE7G,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM;;;;;;;;;EAY/C;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG,SAAS,CAWhI;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW;;;;;;;;;EAIxE;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAY3E;AAED,uFAAuF;AACvF,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO;;;;GAY9F"}

package/dist/brain/project-memory.js

@@ -0,0 +1,76 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { GlobalBrain } from './global-brain.js';
+import { projectRoot, projectLocalPath } from './project-kit.js';
+/** Explicit project-local paths only; never consults the default global store. */
+export function projectStorage(directory) {
+    const root = projectRoot(directory);
+    const storagePath = projectLocalPath(root, '.shadow-brain/project-memory.json');
+    const settingsPath = projectLocalPath(root, '.shadow-brain/feature-settings.json');
+    const annotationsPath = projectLocalPath(root, '.shadow-brain/memory-annotations.json');
+    const journalPath = projectLocalPath(root, '.shadow-brain/activity-journal.json');
+    const feedbackPath = projectLocalPath(root, '.shadow-brain/memory-feedback.json');
+    for (const filename of [storagePath, settingsPath, annotationsPath, journalPath, feedbackPath]) {
+        const stat = fs.lstatSync(filename, { throwIfNoEntry: false });
+        if (stat && (!stat.isFile() || stat.nlink !== 1))
+            throw new Error('Project storage paths must be ordinary unlinked files.');
+    }
+    return { root, projectId: GlobalBrain.projectIdFor(root), projectName: path.basename(root), storagePath, settingsPath, annotationsPath, journalPath, feedbackPath };
+}
+/** Identify an explicit project store even when Windows launch paths use different spellings. */
+export function resolveProjectStore(directory, dbPath) {
+    if (!dbPath)
+        return undefined;
+    const absolute = path.resolve(dbPath);
+    const parent = path.dirname(absolute);
+    if (path.relative(path.join(parent, 'project-memory.json'), absolute) ||
+        path.relative(path.join(path.dirname(parent), '.shadow-brain'), parent))
+        return undefined;
+    // Validate the supplied project ancestor before using its canonical spelling. The store and its directory can be absent.
+    const requestedRoot = projectRoot(path.dirname(parent));
+    const local = projectStorage(directory);
+    if (path.relative(local.root, requestedRoot))
+        throw new TypeError('The explicit project store must belong to the selected project.');
+    return local;
+}
+export function requireProjectStore(directory, brain) {
+    const store = projectStorage(directory);
+    if (path.resolve(brain.dbPath) !== store.storagePath)
+        throw new Error('Project Kit requires its project-local store. Start shadow-brain project workspace in this project, or use its generated MCP recipe.');
+    return store;
+}
+export function parseProjectKnowledge(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new TypeError('Knowledge must be an object.');
+    const value = input;
+    if (Object.keys(value).some(key => !['title', 'content', 'category', 'source'].includes(key)))
+        throw new TypeError('Unknown knowledge field.');
+    const title = value.title;
+    const content = value.content;
+    if (typeof title !== 'string' || !title.trim() || title.length > 160 || /[\u0000-\u001f\u007f]/.test(title))
+        throw new TypeError('Use a single-line title from 1 to 160 characters.');
+    if (typeof content !== 'string' || !content.trim() || content.length > 8000 || content.includes('\0'))
+        throw new TypeError('Knowledge content must contain 1 to 8000 characters without null bytes.');
+    if (value.category !== undefined && (typeof value.category !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 _.-]{0,63}$/.test(value.category.trim())))
+        throw new TypeError('Use a category from 1 to 64 plain characters.');
+    if (value.source !== undefined && (typeof value.source !== 'string' || value.source.length > 500 || /[\u0000-\u001f\u007f]/.test(value.source)))
+        throw new TypeError('A source reference must be at most 500 characters without control characters.');
+    return { title: title.trim(), content, ...(value.category ? { category: value.category.trim() } : {}),
+        ...(value.source && value.source.trim() ? { source: value.source.trim() } : {}) };
+}
+/** Only explicit user knowledge. Source references are labels and are never opened. */
+export async function addProjectKnowledge(directory, brain, input) {
+    const knowledge = parseProjectKnowledge(input);
+    const store = requireProjectStore(directory, brain);
+    await brain.init();
+    brain.refresh();
+    if (brain.getStorageHealth().lastError)
+        throw new Error('Project memory could not be read; no knowledge was added.');
+    const memoryId = brain.writeSync({ projectId: store.projectId, projectName: store.projectName,
+        agentTool: 'user', category: knowledge.category ?? 'knowledge', content: knowledge.title + '\n' + knowledge.content,
+        importance: 0.7, metadata: { origin: 'project-kit-user', inputKind: 'explicit-knowledge', title: knowledge.title,
+            ...(knowledge.source ? { sources: [knowledge.source] } : {}) } });
+    await brain.sync();
+    return { ok: true, memoryId, projectId: store.projectId };
+}
+//# sourceMappingURL=project-memory.js.map

package/dist/brain/project-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-memory.js","sourceRoot":"","sources":["../../src/brain/project-memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIjE,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,EAAE,mCAAmC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,EAAE,qCAAqC,CAAC,CAAC;IACnF,MAAM,eAAe,GAAG,gBAAgB,CAAC,IAAI,EAAE,uCAAuC,CAAC,CAAC;IACxF,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,EAAE,qCAAqC,CAAC,CAAC;IAClF,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,EAAE,oCAAoC,CAAC,CAAC;IAClF,KAAK,MAAM,QAAQ,IAAI,CAAC,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/D,IAAI,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC9H,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;AACtK,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,MAA0B;IAC/E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAAE,QAAQ,CAAC;QACjE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9F,yHAAyH;IACzH,MAAM,aAAa,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,iEAAiE,CAAC,CAAC;IACrI,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,KAAkB;IACvE,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,sIAAsI,CAAC,CAAC;IAC9M,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,8BAA8B,CAAC,CAAC;IACrH,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC;IAC/I,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,IAAI,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;IACtL,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,yEAAyE,CAAC,CAAC;IACtM,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,oCAAoC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;IACpN,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,IAAI,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,+EAA+E,CAAC,CAAC;IACtP,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAG,KAAK,CAAC,QAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/G,GAAG,CAAC,KAAK,CAAC,MAAM,IAAK,KAAK,CAAC,MAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAG,KAAK,CAAC,MAAiB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC9G,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,SAAiB,EAAE,KAAkB,EAAE,KAAc;IAC7F,MAAM,SAAS,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,mBAAmB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACpD,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACnB,KAAK,CAAC,OAAO,EAAE,CAAC;IAChB,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACrH,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW;QAC3F,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,WAAW,EAAE,OAAO,EAAE,SAAS,CAAC,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC,OAAO;QACnH,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,oBAAoB,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK;YAC9G,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACtE,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACnB,OAAO,EAAE,EAAE,EAAE,IAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;AACrE,CAAC"}

package/dist/brain/subconscious.d.ts

@@ -1,34 +1,31 @@
-import { AgentTool, SubconsciousConfig, SubconsciousBriefing, SubconsciousStats } from '../types.js';
+import type { AgentTool, SubconsciousBriefing, SubconsciousConfig, SubconsciousStats } from '../types.js';
+import { FeatureSettingsStore } from './feature-settings.js';
 import { GlobalBrain } from './global-brain.js';
+import { type MemoryAnnotationsStore } from './memory-annotations.js';
+interface BriefingOptions {
+    agentTool: AgentTool;
+    projectDir: string;
+    projectId?: string;
+    projectName?: string;
+    currentTask?: string;
+    includeCrossProject?: boolean;
+}
 export declare class SubconsciousEngine {
     private config;
-    private brain;
-    private stats;
-    constructor(config?: Partial<SubconsciousConfig>, brain?: GlobalBrain);
-    /** Generate a session-start briefing for the agent — proactive context injection */
-    generateBriefing(opts: {
-        agentTool: AgentTool;
-        projectDir: string;
-        projectId?: string;
-        projectName?: string;
-        currentTask?: string;
-    }): Promise<SubconsciousBriefing>;
-    /** Get current stats */
+    private readonly brain;
+    private readonly settings;
+    private readonly annotations;
+    private readonly cache;
+    private readonly stats;
+    constructor(config?: Partial<SubconsciousConfig>, brain?: GlobalBrain, settings?: Pick<FeatureSettingsStore, 'get'>, annotations?: Pick<MemoryAnnotationsStore, 'get'>);
+    /** Generate a session-start briefing from the current project and task. */
+    generateBriefing(opts: BriefingOptions): Promise<SubconsciousBriefing>;
     getStats(): SubconsciousStats;
-    /** Update config at runtime */
     configure(patch: Partial<SubconsciousConfig>): void;
     getConfig(): SubconsciousConfig;
-    private fetchSection;
-    private fetchCrossAgentInsights;
-    private fetchProjectStateSummary;
-    private fetchSimilarWork;
-    private fetchTopPatterns;
-    private extractKeywords;
-    private formatEntry;
-    private assembleBriefing;
-    private trimToBudget;
+    private addSection;
     private emptyBriefing;
-    private runningAvg;
 }
 export declare function getSubconscious(config?: Partial<SubconsciousConfig>): SubconsciousEngine;
+export {};
 //# sourceMappingURL=subconscious.d.ts.map

package/dist/brain/subconscious.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subconscious.d.ts","sourceRoot":"","sources":["../../src/brain/subconscious.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAkB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkBhE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAAoB;gBAErB,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,EAAE,KAAK,CAAC,EAAE,WAAW;IAazE,oFAAoF;IAC9E,gBAAgB,CAAC,IAAI,EAAE;QAC3B,SAAS,EAAE,SAAS,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA4EjC,wBAAwB;IACxB,QAAQ,IAAI,iBAAiB;IAI7B,+BAA+B;IAC/B,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAInD,SAAS,IAAI,kBAAkB;IAM/B,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,gBAAgB;IA8CxB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,UAAU;CAGnB;AAID,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAIxF"}
+{"version":3,"file":"subconscious.d.ts","sourceRoot":"","sources":["../../src/brain/subconscious.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE1G,OAAO,EAA6B,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,EAAkB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAAwB,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAW5F,UAAU,eAAe;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsE;IAC5F,OAAO,CAAC,QAAQ,CAAC,KAAK,CAOpB;gBAGA,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,EACxC,KAAK,CAAC,EAAE,WAAW,EACnB,QAAQ,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,KAAK,CAAC,EAC5C,WAAW,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC;IAUnD,2EAA2E;IACrE,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkD5E,QAAQ,IAAI,iBAAiB;IAI7B,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI;IAKnD,SAAS,IAAI,kBAAkB;IAI/B,OAAO,CAAC,UAAU;IAiBlB,OAAO,CAAC,aAAa;CAkBtB;AAID,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAIxF"}