@teamvibe/poller 0.8.9-rc.1 → 0.8.9-rc.2

package/README.md

@@ -100,6 +100,41 @@ The poller authenticates with the TeamVibe API using your token, then continuous
 
 Passive usage percentages remain usable lower bounds until each window's `resetAt`. Without a reset time, passive windows expire five minutes after observation. Probe windows retain their 60-second TTL. Reset windows are ignored; known accounts still rank before unknown accounts. A window at the account's threshold defers selection until its expiry (reset for passive windows, TTL fallback without a reset).
 
+### Brain inventory event (#517)
+
+The existing `/events` queue carries `brain.inventory` alongside session, pool,
+maintenance and poller events. Collection runs after pull, before Claude starts,
+for normal **and maintenance** sessions. Per workspace/brain, unchanged snapshots
+are suppressed for 10 minutes; changes to inventory, HEAD, or poller version emit
+immediately. Collection failures log a generic warning and never block the agent.
+
+`metadata` is additive and versioned:
+
+```ts
+{
+  schemaVersion: 1,
+  workspaceId, brainId, repo, commit, pollerVersion,
+  skills: [{ name, path, discovered, state, description?, source?, ref?, sha?, contentHash? }],
+  mcpServers: [{ name, type, requiredEnv: string[], missingEnv: string[] }],
+  locks: { skillsLockJson: boolean, skillsLockYaml: boolean },
+  inventoryHash
+}
+```
+
+Only flat `.claude/skills/<name>/SKILL.md` directories are discovered. Nested skills
+are reported as `not-discovered`; missing or invalid YAML frontmatter is `invalid`.
+A lock entry makes a valid flat skill `vendored`; other valid flat skills are `own`.
+Both `skills-lock.json` and `.claude/skills/skills.lock.yaml` are optional; wrapper
+YAML provenance takes precedence over JSON. `contentHash` hashes actual skill files.
+MCP `${VAR}` and `${VAR:-default}` placeholders in `env` and `headers` produce names
+only, compared with defined keys in the resolved spawn environment. No commands,
+URLs, headers, literal credentials, or environment values from `.mcp.json` are sent.
+Symlinked files/directories are not followed. Git repository URL credentials and
+query strings are removed from event attribution.
+
+See [#517](https://github.com/teamvibeai/teamvibe.ai/issues/517). Read-only v1;
+updates/additions and scheduled skill maintenance actions are follow-up work.
+
 ## Channel Git credentials
 
 See [Agent Git credentials](docs/git-credentials.md) for multi-host channel bindings,

package/dist/brain-inventory-emitter.d.ts

@@ -0,0 +1,13 @@
+export declare function shouldEmitInventory(previous: {
+    hash: string;
+    at: number;
+} | undefined, hash: string, now: number): boolean;
+/** Best effort telemetry; a malformed brain or unavailable git must never block Claude. */
+export declare function emitBrainInventory(params: {
+    brainPath: string;
+    brainId: string;
+    workspaceId: string;
+    channelId: string;
+    repo: string;
+    envNames: string[];
+}): Promise<void>;

package/dist/brain-inventory-emitter.js

@@ -0,0 +1,57 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { collectBrainInventory } from './brain-inventory.js';
+import { emitEvent } from './event-queue.js';
+import { POLLER_VERSION } from './config.js';
+import { logger } from './logger.js';
+const exec = promisify(execFile);
+const lastEmitted = new Map();
+const INTERVAL_MS = 10 * 60_000;
+export function shouldEmitInventory(previous, hash, now) {
+    return !previous || previous.hash !== hash || now - previous.at >= INTERVAL_MS;
+}
+/** Best effort telemetry; a malformed brain or unavailable git must never block Claude. */
+export async function emitBrainInventory(params) {
+    try {
+        const inventory = await collectBrainInventory(params.brainPath, params.envNames);
+        const { stdout } = await exec('git', [
+            '-C',
+            params.brainPath,
+            'rev-parse',
+            'HEAD',
+        ]);
+        const commit = stdout.trim();
+        // Include HEAD in throttling so an unrelated commit is still reflected in attribution.
+        const hash = `${inventory.inventoryHash}:${commit}:${POLLER_VERSION}`;
+        const key = `${params.workspaceId}:${params.brainId}`;
+        const now = Date.now();
+        if (!shouldEmitInventory(lastEmitted.get(key), hash, now))
+            return;
+        let repo = params.repo;
+        try {
+            const url = new URL(repo);
+            url.username = '';
+            url.password = '';
+            url.search = '';
+            url.hash = '';
+            repo = url.toString();
+        }
+        catch {
+            /* SSH remotes carry no HTTP credentials. */
+        }
+        emitEvent('brain.inventory', params.channelId, {
+            schemaVersion: 1,
+            workspaceId: params.workspaceId,
+            brainId: params.brainId,
+            repo,
+            commit,
+            pollerVersion: POLLER_VERSION,
+            ...inventory,
+        });
+        lastEmitted.set(key, { hash, at: now });
+    }
+    catch {
+        // Do not echo parser exceptions: they can contain raw MCP credential values.
+        logger.warn('[BrainInventory] Could not collect inventory');
+    }
+}

package/dist/brain-inventory.d.ts

@@ -0,0 +1,28 @@
+export interface InventorySkill {
+    name: string;
+    path: string;
+    discovered: boolean;
+    state: 'own' | 'vendored' | 'not-discovered' | 'invalid';
+    target?: string;
+    description?: string;
+    source?: string;
+    ref?: string;
+    sha?: string;
+    contentHash: string;
+}
+export interface InventoryMcpServer {
+    name: string;
+    type: 'stdio' | 'http';
+    requiredEnv: string[];
+    missingEnv: string[];
+}
+/** Read-only, deterministic collection. Receives env NAMES; never accepts env values. */
+export declare function collectBrainInventory(brainPath: string, envNames: readonly string[]): Promise<{
+    inventoryHash: string;
+    skills: InventorySkill[];
+    mcpServers: InventoryMcpServer[];
+    locks: {
+        skillsLockJson: boolean;
+        skillsLockYaml: boolean;
+    };
+}>;

package/dist/brain-inventory.js

@@ -0,0 +1,209 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile, lstat, realpath } from 'node:fs/promises';
+import { join, posix, relative as relativePath, isAbsolute, sep, } from 'node:path';
+import { parse } from 'yaml';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+async function optionalFile(path) {
+    try {
+        if (!(await lstat(path)).isFile())
+            return undefined; // Never follow symlinks out of the brain.
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return undefined;
+        throw error;
+    }
+}
+function document(text, yaml = false) {
+    try {
+        return object(text === undefined
+            ? undefined
+            : yaml
+                ? parse(text, { maxAliasCount: 0 })
+                : JSON.parse(text));
+    }
+    catch {
+        return {};
+    } // Bad optional locks/config must not prevent the remaining inventory.
+}
+async function entries(path) {
+    try {
+        return (await readdir(path, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name, 'en'));
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return [];
+        throw error;
+    }
+}
+async function directoryHash(path) {
+    const parts = [];
+    for (const entry of await entries(path)) {
+        if (['.git', 'node_modules'].includes(entry.name))
+            continue;
+        if (entry.isFile())
+            parts.push(`${entry.name}\0${hash(await readFile(join(path, entry.name)))}`);
+        if (entry.isDirectory())
+            parts.push(`${entry.name}/\0${await directoryHash(join(path, entry.name))}`);
+    }
+    return hash(parts.join('\n'));
+}
+/** Read-only, deterministic collection. Receives env NAMES; never accepts env values. */
+export async function collectBrainInventory(brainPath, envNames) {
+    const brainRoot = await realpath(brainPath);
+    const skillsPath = join(brainRoot, '.claude/skills');
+    const [jsonText, yamlText, mcpText] = await Promise.all([
+        optionalFile(join(brainPath, 'skills-lock.json')),
+        optionalFile(join(skillsPath, 'skills.lock.yaml')),
+        optionalFile(join(brainPath, '.mcp.json')),
+    ]);
+    const jsonLocks = object(document(jsonText)['skills']);
+    const yamlLocks = object(document(yamlText, true)['skills']);
+    const skills = [];
+    async function walk(path, relative, depth, ancestors) {
+        for (const entry of await entries(path)) {
+            if ((!entry.isDirectory() && !entry.isSymbolicLink()) ||
+                ['.git', 'node_modules'].includes(entry.name))
+                continue;
+            let child = join(path, entry.name);
+            const skillPath = posix.join(relative, entry.name);
+            let target;
+            const invalidLink = () => skills.push({
+                name: entry.name,
+                path: skillPath,
+                discovered: false,
+                state: 'invalid',
+                contentHash: hash(''), // No target files are read for unsafe or dangling links.
+            });
+            if (entry.isSymbolicLink()) {
+                try {
+                    child = await realpath(child);
+                    const resolved = relativePath(brainRoot, child);
+                    if (resolved === '..' ||
+                        resolved.startsWith(`..${sep}`) ||
+                        isAbsolute(resolved) ||
+                        ancestors.has(child)) {
+                        invalidLink();
+                        continue;
+                    }
+                    if (!(await lstat(child)).isDirectory()) {
+                        invalidLink();
+                        continue;
+                    }
+                    target = resolved.split(sep).join('/');
+                }
+                catch (error) {
+                    if (!['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code ?? ''))
+                        throw error;
+                    invalidLink();
+                    continue;
+                }
+            }
+            const text = await optionalFile(join(child, 'SKILL.md'));
+            if (text !== undefined) {
+                const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+                let front = {};
+                try {
+                    if (match)
+                        front = object(parse(match[1], { maxAliasCount: 0 }));
+                }
+                catch {
+                    /* invalid */
+                }
+                const valid = (front['name'] === undefined || front['name'] === entry.name) &&
+                    typeof front['description'] === 'string' &&
+                    !!front['description'].trim();
+                const flat = depth === 0;
+                const provenance = flat
+                    ? {
+                        ...object(jsonLocks[entry.name]),
+                        ...object(yamlLocks[entry.name]),
+                    }
+                    : {};
+                const vendored = flat &&
+                    (target !== undefined ||
+                        Object.hasOwn(jsonLocks, entry.name) ||
+                        Object.hasOwn(yamlLocks, entry.name));
+                const skill = {
+                    name: entry.name,
+                    path: skillPath,
+                    discovered: flat && valid,
+                    state: !valid
+                        ? 'invalid'
+                        : !flat
+                            ? 'not-discovered'
+                            : vendored
+                                ? 'vendored'
+                                : 'own',
+                    contentHash: await directoryHash(child),
+                };
+                if (target !== undefined)
+                    skill.target = target;
+                if (typeof front['description'] === 'string')
+                    skill.description = front['description'];
+                for (const key of ['source', 'ref', 'sha']) {
+                    if (typeof provenance[key] === 'string') {
+                        let value = provenance[key];
+                        if (key === 'source') {
+                            try {
+                                const url = new URL(value);
+                                url.username = '';
+                                url.password = '';
+                                url.search = '';
+                                url.hash = '';
+                                value = url.toString();
+                            }
+                            catch {
+                                /* owner/repo or SSH syntax */
+                            }
+                        }
+                        skill[key] = value;
+                    }
+                }
+                skills.push(skill);
+            }
+            else if (target !== undefined) {
+                invalidLink();
+            }
+            await walk(child, skillPath, depth + 1, new Set([...ancestors, child]));
+        }
+    }
+    await walk(skillsPath, '.claude/skills', 0, new Set([brainRoot, skillsPath]));
+    const present = new Set(envNames);
+    const mcpServers = Object.entries(object(document(mcpText)['mcpServers']))
+        .sort(([a], [b]) => a.localeCompare(b, 'en'))
+        .map(([name, raw]) => {
+        const server = object(raw);
+        const names = new Set();
+        // Only env/headers placeholder references are part of the credential contract.
+        for (const value of [
+            ...Object.values(object(server['env'])),
+            ...Object.values(object(server['headers'])),
+        ]) {
+            if (typeof value !== 'string')
+                continue;
+            for (const match of value.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}/g))
+                names.add(match[1]);
+        }
+        const requiredEnv = [...names].sort();
+        return {
+            name,
+            type: server['type'] === 'http' || server['type'] === 'sse' || server['url']
+                ? 'http'
+                : 'stdio',
+            requiredEnv,
+            missingEnv: requiredEnv.filter((name) => !present.has(name)),
+        };
+    });
+    const inventory = {
+        skills,
+        mcpServers,
+        locks: {
+            skillsLockJson: jsonText !== undefined,
+            skillsLockYaml: yamlText !== undefined,
+        },
+    };
+    return { ...inventory, inventoryHash: hash(JSON.stringify(inventory)) };
+}

package/dist/claude-spawner.js

@@ -1,3 +1,4 @@
+import { emitBrainInventory } from './brain-inventory-emitter.js';
 import { END_OF_TURN_NO_FURTHER_RESPONSE_SENTINEL } from './end-of-turn-sentinel.js';
 import { createSessionInstance, writeSessionOwner } from './session-instance.js';
 import { buildGitCredentialEnv } from './git-credential-env.js';
@@ -913,6 +914,40 @@ async function runClaudeCode(msg, sessionLog, cwd, directory, sessionId, isFirst
         workspaceId: msg.teamvibe.workspaceId,
         channelId: msg.teamvibe.channelId,
     });
+    // Prepend persistent bin dir to PATH if configured
+    const envPath = config.PERSISTENT_STORAGE_PATH
+        ? `${config.PERSISTENT_STORAGE_PATH}/bin:${process.env['PATH'] || ''}`
+        : process.env['PATH'];
+    if (runtime?.account)
+        poolInfo(sessionLog, `token target account=${poolLabel(runtime.account)} session=${JSON.stringify(sessionId ?? 'new')} credential=selected account token`);
+    const spawnEnv = buildSpawnEnv({
+        spawnSecretsEnv: spawnSecrets.env.unwrap(),
+        processEnv: process.env,
+        envPath,
+        claudeConfigDir: runtime?.claudeConfigDir ?? getBaseBrainPath(),
+        persistentStoragePath: config.PERSISTENT_STORAGE_PATH,
+        slackContext,
+        teamvibeApiUrl: config.TEAMVIBE_API_URL,
+        teamvibePollerToken: config.TEAMVIBE_POLLER_TOKEN || '',
+        teamvibeWorkspaceId: msg.teamvibe.workspaceId,
+        teamvibeChannelId: msg.teamvibe.channelId,
+        teamvibeBotId: msg.teamvibe.botId,
+        teamvibePollerId: getPollerId() || '',
+        inboxThreadId: msg.thread_id,
+        brainPath: directory.path,
+        subscriptionAccount: runtime?.account,
+        gitCredential,
+        gitTokenFile: gitDelivery.session?.tokenFile,
+    });
+    // Ordinary and maintenance sessions pass here after pull and all credential overlays.
+    // Only defined names from the final spawn environment cross the collector boundary.
+    if (directory.brainId && msg.teamvibe.brain?.gitRepoUrl) {
+        await emitBrainInventory({
+            brainPath: cwd, brainId: directory.brainId, workspaceId: directory.workspaceId,
+            channelId: msg.teamvibe.channelId, repo: msg.teamvibe.brain.gitRepoUrl,
+            envNames: Object.keys(spawnEnv).filter(name => spawnEnv[name] !== undefined),
+        });
+    }
     if (runtime?.account)
         await validateAccount(runtime.account, runtime.resolved);
     if (runtime?.account && !runtime.shouldStop()) {
@@ -1009,31 +1044,6 @@ async function runClaudeCode(msg, sessionLog, cwd, directory, sessionId, isFirst
             const imageCount = (msg.inlineImages ?? []).filter((img) => img.data || img.url).length;
             sessionLog.info(`Inline image content: ${imageCount} image(s) sent via stream-json stdin (not logged)`);
         }
-        // Prepend persistent bin dir to PATH if configured
-        const envPath = config.PERSISTENT_STORAGE_PATH
-            ? `${config.PERSISTENT_STORAGE_PATH}/bin:${process.env['PATH'] || ''}`
-            : process.env['PATH'];
-        if (runtime?.account)
-            poolInfo(sessionLog, `token target account=${poolLabel(runtime.account)} session=${JSON.stringify(sessionId ?? 'new')} credential=selected account token`);
-        const spawnEnv = buildSpawnEnv({
-            spawnSecretsEnv: spawnSecrets.env.unwrap(),
-            processEnv: process.env,
-            envPath,
-            claudeConfigDir: runtime?.claudeConfigDir ?? getBaseBrainPath(),
-            persistentStoragePath: config.PERSISTENT_STORAGE_PATH,
-            slackContext,
-            teamvibeApiUrl: config.TEAMVIBE_API_URL,
-            teamvibePollerToken: config.TEAMVIBE_POLLER_TOKEN || '',
-            teamvibeWorkspaceId: msg.teamvibe.workspaceId,
-            teamvibeChannelId: msg.teamvibe.channelId,
-            teamvibeBotId: msg.teamvibe.botId,
-            teamvibePollerId: getPollerId() || '',
-            inboxThreadId: msg.thread_id,
-            brainPath: directory.path,
-            subscriptionAccount: runtime?.account,
-            gitCredential,
-            gitTokenFile: gitDelivery.session?.tokenFile,
-        });
         // Capture the actual credentials for this attempt, including pool selection
         // and secrets overlays, regardless of whether alias exposure is enabled.
         const outputTokens = [spawnEnv['CLAUDE_CODE_OAUTH_TOKEN'], spawnEnv['TEAMVIBE_CLAUDE_OAUTH_TOKEN'], spawnEnv['GH_TOKEN'], spawnEnv['GITHUB_TOKEN']]

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.8.9-rc.1",
+  "version": "0.8.9-rc.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@teamvibe/poller",
-      "version": "0.8.9-rc.1",
+      "version": "0.8.9-rc.2",
       "dependencies": {
         "@aws-sdk/client-dynamodb": "3.1108.0",
         "@aws-sdk/client-sqs": "3.1108.0",
@@ -15,6 +15,7 @@
         "@slack/web-api": "^7.0.0",
         "croner": "^10.0.1",
         "dotenv": "^17.2.3",
+        "yaml": "2.8.1",
         "zod": "^3.22.0"
       },
       "bin": {
@@ -1594,6 +1595,18 @@
       "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
       "license": "MIT"
     },
+    "node_modules/yaml": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.1.tgz",
+      "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      }
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.8.9-rc.1",
+  "version": "0.8.9-rc.2",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
@@ -34,6 +34,7 @@
     "@slack/web-api": "^7.0.0",
     "croner": "^10.0.1",
     "dotenv": "^17.2.3",
+    "yaml": "2.8.1",
     "zod": "^3.22.0"
   },
   "devDependencies": {