@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/tools/skills/obsidian-readiness.d.ts

@@ -0,0 +1,16 @@
+export declare const OBSIDIAN_SKILL_NAME = "obsidian";
+export declare const OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY = "obsidian_vault_path";
+export declare const OBSIDIAN_BIN_CANDIDATES: Readonly<Record<string, readonly string[]>>;
+export declare const OBSIDIAN_CONFIG_CANDIDATES: Readonly<Record<string, readonly string[]>>;
+export declare function expandObsidianPath(candidate: string, env?: Record<string, string | undefined>, home?: string): string;
+export declare function firstExistingPath(candidates: readonly string[], expand: (candidate: string) => string, exists: (candidate: string) => boolean): string | null;
+export type ObsidianPathProbe = {
+    expand?: (candidate: string) => string;
+    exists?: (candidate: string) => boolean;
+    readText?: (candidate: string) => string;
+};
+export declare function obsidianInstallState(platform: string | undefined, probe?: ObsidianPathProbe): 'installed' | 'missing';
+export declare function parseObsidianCliEnabled(text: string): boolean | null;
+export declare function obsidianCliState(platform: string | undefined, probe?: ObsidianPathProbe): 'enabled' | 'disabled' | 'unknown';
+export declare function isSandboxedWorkbenchInstall(env?: Record<string, string | undefined>): boolean;
+export declare function isObsidianVaultPath(value: string | null, existsDir?: (candidate: string) => boolean): boolean;

package/dist-lib/lib/tools/skills/obsidian-readiness.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+import process from 'process';
+export const OBSIDIAN_SKILL_NAME = 'obsidian';
+export const OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY = 'obsidian_vault_path';
+export const OBSIDIAN_BIN_CANDIDATES = {
+    darwin: [
+        '/Applications/Obsidian.app/Contents/MacOS/obsidian',
+        '~/Applications/Obsidian.app/Contents/MacOS/obsidian',
+        '/usr/local/bin/obsidian'
+    ],
+    linux: [
+        '/usr/bin/obsidian',
+        '/usr/local/bin/obsidian',
+        '~/.local/bin/obsidian',
+        '/opt/Obsidian/obsidian',
+        '/snap/bin/obsidian'
+    ],
+    win32: [
+        '%LOCALAPPDATA%\\Programs\\Obsidian\\Obsidian.exe',
+        '%LOCALAPPDATA%\\Obsidian\\Obsidian.exe',
+        '%ProgramFiles%\\Obsidian\\Obsidian.exe',
+        '%ProgramFiles(x86)%\\Obsidian\\Obsidian.exe'
+    ]
+};
+export const OBSIDIAN_CONFIG_CANDIDATES = {
+    darwin: ['~/Library/Application Support/obsidian/obsidian.json'],
+    linux: [
+        '~/.config/obsidian/obsidian.json',
+        '~/snap/obsidian/current/.config/obsidian/obsidian.json',
+        '~/.var/app/md.obsidian.Obsidian/config/obsidian/obsidian.json'
+    ],
+    win32: ['%APPDATA%\\obsidian\\obsidian.json']
+};
+function environment() {
+    return process.env;
+}
+export function expandObsidianPath(candidate, env = environment(), home = homedir()) {
+    const withHome = candidate.startsWith('~/') ? path.join(home, candidate.slice(2)) : candidate;
+    return withHome.replace(/\$([A-Za-z_][A-Za-z0-9_]*)|%([^%]+)%/g, (_match, unix, windows) => env[unix ?? windows ?? ''] ?? '');
+}
+export function firstExistingPath(candidates, expand, exists) {
+    for (const candidate of candidates) {
+        const expanded = expand(candidate);
+        if (expanded && exists(expanded))
+            return expanded;
+    }
+    return null;
+}
+export function obsidianInstallState(platform, probe = {}) {
+    const expand = probe.expand ?? ((candidate) => expandObsidianPath(candidate));
+    const exists = probe.exists ?? ((candidate) => fs.existsSync(candidate));
+    const installed = firstExistingPath(OBSIDIAN_BIN_CANDIDATES[platform ?? ''] ?? [], expand, exists);
+    return installed ? 'installed' : 'missing';
+}
+export function parseObsidianCliEnabled(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value.cli === 'boolean' ? value.cli : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function obsidianCliState(platform, probe = {}) {
+    const expand = probe.expand ?? ((candidate) => expandObsidianPath(candidate));
+    const exists = probe.exists ?? ((candidate) => fs.existsSync(candidate));
+    const readText = probe.readText ?? ((candidate) => fs.readFileSync(candidate, 'utf8'));
+    const config = firstExistingPath(OBSIDIAN_CONFIG_CANDIDATES[platform ?? ''] ?? [], expand, exists);
+    if (!config)
+        return 'unknown';
+    try {
+        const enabled = parseObsidianCliEnabled(readText(config));
+        return enabled === null ? 'unknown' : enabled ? 'enabled' : 'disabled';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function isSandboxedWorkbenchInstall(env = environment()) {
+    return Boolean(env.SNAP || env.FLATPAK_ID);
+}
+export function isObsidianVaultPath(value, existsDir = (candidate) => {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (!value)
+        return false;
+    return existsDir(path.join(value, '.obsidian'));
+}

package/dist-lib/lib/tools/skills/overlay-crud.d.ts

@@ -0,0 +1,18 @@
+export interface ManagedSkill {
+    readonly name: string;
+    readonly origin: 'base' | 'overlay';
+    readonly overridesBase: boolean;
+}
+export interface SkillFileContent {
+    readonly content: string;
+    readonly origin: 'base' | 'overlay';
+}
+export declare function listManagedSkills(baseDir: string, overlayDir: string | null): Promise<ManagedSkill[]>;
+export declare function readSkillFile(baseDir: string, overlayDir: string | null, name: string): Promise<SkillFileContent | null>;
+export declare function writeSkillFile(overlayDir: string, name: string, content: string): Promise<string>;
+export declare function copyBaseForEdit(baseDir: string, overlayDir: string, name: string): Promise<{
+    copied: boolean;
+}>;
+export declare function deleteOverlaySkill(overlayDir: string, name: string): Promise<{
+    removed: boolean;
+}>;

package/dist-lib/lib/tools/skills/overlay-crud.js

@@ -0,0 +1,98 @@
+import fs from 'fs';
+import path from 'path';
+import { randomSuffix } from "./bundled-dir.js";
+const SAFE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function assertSafeName(name) {
+    if (!SAFE_NAME.test(name)) {
+        throw new Error(`invalid skill name: ${name}`);
+    }
+}
+async function dirNames(root) {
+    try {
+        const entries = await fs.promises.readdir(root, { withFileTypes: true });
+        return new Set(entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
+    }
+    catch {
+        return new Set();
+    }
+}
+async function readIfPresent(file) {
+    try {
+        return await fs.promises.readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function listManagedSkills(baseDir, overlayDir) {
+    const base = await dirNames(baseDir);
+    const overlay = overlayDir ? await dirNames(overlayDir) : new Set();
+    const names = [...new Set([...base, ...overlay])].sort((a, b) => a.localeCompare(b));
+    return names.map((name) => {
+        const inOverlay = overlay.has(name);
+        return {
+            name,
+            origin: inOverlay ? 'overlay' : 'base',
+            overridesBase: inOverlay && base.has(name)
+        };
+    });
+}
+export async function readSkillFile(baseDir, overlayDir, name) {
+    assertSafeName(name);
+    if (overlayDir) {
+        const over = await readIfPresent(path.join(overlayDir, name, 'SKILL.md'));
+        if (over !== null)
+            return { content: over, origin: 'overlay' };
+    }
+    const base = await readIfPresent(path.join(baseDir, name, 'SKILL.md'));
+    return base !== null ? { content: base, origin: 'base' } : null;
+}
+export async function writeSkillFile(overlayDir, name, content) {
+    assertSafeName(name);
+    const skillDir = path.join(overlayDir, name);
+    await fs.promises.mkdir(skillDir, { recursive: true });
+    const target = path.join(skillDir, 'SKILL.md');
+    const tmp = `${target}.tmp-${randomSuffix()}`;
+    await fs.promises.writeFile(tmp, content);
+    await fs.promises.rename(tmp, target);
+    return skillDir;
+}
+export async function copyBaseForEdit(baseDir, overlayDir, name) {
+    assertSafeName(name);
+    const dest = path.join(overlayDir, name);
+    if (await exists(dest))
+        return { copied: false };
+    const src = path.join(baseDir, name);
+    if (!(await exists(src)))
+        throw new Error(`skill not found: ${name}`);
+    await copyDir(src, dest);
+    return { copied: true };
+}
+export async function deleteOverlaySkill(overlayDir, name) {
+    assertSafeName(name);
+    const dir = path.join(overlayDir, name);
+    if (!(await exists(dir)))
+        return { removed: false };
+    await fs.promises.rm(dir, { recursive: true, force: true });
+    return { removed: true };
+}
+async function exists(target) {
+    try {
+        await fs.promises.lstat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function copyDir(src, dest) {
+    await fs.promises.mkdir(dest, { recursive: true });
+    for (const entry of await fs.promises.readdir(src, { withFileTypes: true })) {
+        const from = path.join(src, entry.name);
+        const to = path.join(dest, entry.name);
+        if (entry.isDirectory())
+            await copyDir(from, to);
+        else if (entry.isFile())
+            await fs.promises.writeFile(to, await fs.promises.readFile(from));
+    }
+}

package/dist-lib/lib/tools/skills/overlay-dir.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveSkillsOverlayDir(env?: NodeJS.ProcessEnv): string | null;
+export declare function ensureSkillsOverlayDir(env?: NodeJS.ProcessEnv): Promise<string | null>;

package/dist-lib/lib/tools/skills/overlay-dir.js

@@ -0,0 +1,22 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import process from 'process';
+const SDK_CONFIG_PATH_ENV = 'QVAC_CONFIG_PATH';
+const OVERLAY_DIR_NAME = 'skills';
+export function resolveSkillsOverlayDir(env = process.env) {
+    const configPath = env[SDK_CONFIG_PATH_ENV];
+    if (!configPath)
+        return null;
+    return path.join(path.dirname(configPath), OVERLAY_DIR_NAME);
+}
+export function ensureSkillsOverlayDir(env = process.env) {
+    const dir = resolveSkillsOverlayDir(env);
+    return dir ? materialize(dir) : Promise.resolve(null);
+}
+async function materialize(dir) {
+    await fs.promises.mkdir(dir, { recursive: true });
+    if (os.platform() !== 'win32')
+        await fs.promises.chmod(dir, 0o700);
+    return dir;
+}

package/dist-lib/lib/tools/skills/overlay-watch.d.ts

@@ -0,0 +1,13 @@
+export interface OverlayWatcher {
+    stop(): void;
+}
+export type OverlayChangeStream = AsyncIterable<{
+    diff?: readonly unknown[];
+}> & {
+    destroy?: () => void;
+};
+export type WatchStreamFactory = (overlayDir: string) => OverlayChangeStream;
+export declare function watchSkillsOverlay(overlayDir: string, onChange: () => void, opts?: {
+    debounceMs?: number;
+    createStream?: WatchStreamFactory;
+}): OverlayWatcher;

package/dist-lib/lib/tools/skills/overlay-watch.js

@@ -0,0 +1,44 @@
+import Localdrive from 'localdrive';
+import watch from 'watch-drive';
+export function watchSkillsOverlay(overlayDir, onChange, opts = {}) {
+    const debounceMs = opts.debounceMs ?? 200;
+    const createStream = opts.createStream ?? defaultStream;
+    const stream = createStream(overlayDir);
+    let stopped = false;
+    let timer = null;
+    const schedule = () => {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = null;
+            if (!stopped)
+                onChange();
+        }, debounceMs);
+    };
+    void (async () => {
+        try {
+            for await (const batch of stream) {
+                if (batch?.diff && batch.diff.length > 0)
+                    schedule();
+            }
+        }
+        catch {
+        }
+    })();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+            stream.destroy?.();
+        }
+    };
+}
+function defaultStream(overlayDir) {
+    return watch(new Localdrive(overlayDir), '/');
+}

package/dist-lib/lib/tools/skills/scope-key.d.ts

@@ -0,0 +1,7 @@
+export interface CredentialScope {
+    readonly agentId?: string | null | undefined;
+    readonly skill?: string | null | undefined;
+    readonly key: string;
+}
+export declare function scopeKey({ agentId, skill, key }: CredentialScope): string;
+export declare function isDeviceSharedCredentialKey(key: string): boolean;

package/dist-lib/lib/tools/skills/scope-key.js

@@ -0,0 +1,7 @@
+export function scopeKey({ agentId, skill, key }) {
+    return `${agentId ?? ''}\0${skill ?? ''}\0${key}`;
+}
+const DEVICE_SHARED_CREDENTIAL_KEYS = new Set(['obsidian_vault_path']);
+export function isDeviceSharedCredentialKey(key) {
+    return DEVICE_SHARED_CREDENTIAL_KEYS.has(key);
+}

package/dist-lib/lib/tools/skills/setup-routes.d.ts

@@ -0,0 +1,4 @@
+import type { SkillCatalogEntry } from './catalog.ts';
+import type { SkillSetup } from './manifest.ts';
+import { type SkillState } from './skill-state.ts';
+export declare function deriveSetup(entry: SkillCatalogEntry, state: SkillState): SkillSetup | undefined;

package/dist-lib/lib/tools/skills/setup-routes.js

@@ -0,0 +1,14 @@
+import { SKILL_STATE } from "./skill-state.js";
+export function deriveSetup(entry, state) {
+    if (!entry.setup)
+        return undefined;
+    return {
+        ...entry.setup,
+        ...(entry.setup.routes
+            ? { routes: entry.setup.routes.map((route) => withSatisfied(route, state)) }
+            : {})
+    };
+}
+function withSatisfied(route, state) {
+    return route.kind === 'install' ? { ...route, satisfied: state === SKILL_STATE.ready } : route;
+}

package/dist-lib/lib/tools/skills/skill-settings.d.ts

@@ -0,0 +1,16 @@
+import type { SkillSetup, SkillSetupField } from './manifest.ts';
+export interface SkillSettingEntry {
+    readonly skill: string;
+    readonly key: string;
+    readonly value: string;
+    readonly agentId?: string | null;
+}
+export type SkillSettingsFn = (skill: string, agentId?: string | null) => Promise<Readonly<Record<string, string>>> | Readonly<Record<string, string>>;
+export interface SkillSettingsEntry {
+    readonly setup?: SkillSetup | undefined;
+}
+export declare function requiredSettings(entry: SkillSettingsEntry): readonly string[];
+export declare function isSettingField(field: SkillSetupField): boolean;
+export declare function settingEnvName(skill: string, key: string): string;
+export declare function settingsEnv(skill: string, settings: Readonly<Record<string, string>>): Record<string, string>;
+export declare function settingsScopeKey(skill: string, agentId?: string | null): string;

package/dist-lib/lib/tools/skills/skill-settings.js

@@ -0,0 +1,33 @@
+import { scopeKey } from "./scope-key.js";
+function setupFields(entry) {
+    return (entry.setup?.routes ?? []).flatMap((route) => route.fields ?? []);
+}
+export function requiredSettings(entry) {
+    return [
+        ...new Set(setupFields(entry)
+            .filter((field) => field.required === true && field.secret !== true)
+            .map((field) => field.key))
+    ];
+}
+export function isSettingField(field) {
+    return field.secret !== true;
+}
+export function settingEnvName(skill, key) {
+    return `QVAC_SKILL_${envToken(skill)}_${settingKeyToken(key)}`;
+}
+function envToken(value) {
+    return value.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+}
+function settingKeyToken(value) {
+    return value.toUpperCase().replace(/-/g, '_H_').replace(/[^A-Z0-9_]/g, '_');
+}
+export function settingsEnv(skill, settings) {
+    const env = {};
+    for (const [key, value] of Object.entries(settings)) {
+        env[settingEnvName(skill, key)] = value;
+    }
+    return env;
+}
+export function settingsScopeKey(skill, agentId) {
+    return scopeKey({ agentId, skill, key: '' });
+}

package/dist-lib/lib/tools/skills/skill-state-constants.d.ts

@@ -0,0 +1,12 @@
+export declare const SKILL_STATE: {
+    readonly ready: "ready";
+    readonly needsSetup: "needs-setup";
+    readonly disconnected: "disconnected";
+    readonly unsupported: "unsupported";
+    readonly disabled: "disabled";
+    readonly outdated: "outdated";
+    readonly incompatibleModel: "incompatible-model";
+    readonly failed: "failed";
+};
+export type SkillState = (typeof SKILL_STATE)[keyof typeof SKILL_STATE];
+export declare function isAvailableState(state: SkillState): boolean;

package/dist-lib/lib/tools/skills/skill-state-constants.js

@@ -0,0 +1,14 @@
+export const SKILL_STATE = {
+    ready: 'ready',
+    needsSetup: 'needs-setup',
+    disconnected: 'disconnected',
+    unsupported: 'unsupported',
+    disabled: 'disabled',
+    outdated: 'outdated',
+    incompatibleModel: 'incompatible-model',
+    failed: 'failed'
+};
+const AVAILABLE_STATES = new Set([SKILL_STATE.ready]);
+export function isAvailableState(state) {
+    return AVAILABLE_STATES.has(state);
+}

package/dist-lib/lib/tools/skills/skill-state.d.ts

@@ -0,0 +1,40 @@
+import { type CredentialStoreFn } from './auth-resolver.ts';
+import type { SkillRequires, SkillSetup } from './manifest.ts';
+import { type SkillSettingsFn } from './skill-settings.ts';
+import { type ObsidianPathProbe } from './obsidian-readiness.ts';
+import { type CapabilityProfile } from '../../models/model-catalog.ts';
+import { SKILL_STATE, isAvailableState, type SkillState } from './skill-state-constants.ts';
+export { SKILL_STATE, isAvailableState, type SkillState };
+export interface SkillStateEntry {
+    readonly name: string;
+    readonly credentials: readonly string[];
+    readonly platform: readonly string[];
+    readonly requires?: SkillRequires;
+    readonly stub?: boolean;
+    readonly minCapabilityProfile?: string;
+    readonly setup?: SkillSetup;
+}
+export interface SkillStateInputs {
+    readonly credentialStore?: CredentialStoreFn | undefined;
+    readonly settingsStore?: SkillSettingsFn | undefined;
+    readonly platform?: string | undefined;
+    readonly rejected?: ReadonlySet<string>;
+    readonly agentId?: string | null | undefined;
+    readonly binVersions?: ReadonlyMap<string, 'ok' | 'too-old' | 'unknown'> | undefined;
+    readonly activeProfile?: CapabilityProfile | undefined;
+    readonly obsidianProbe?: ObsidianPathProbe;
+    readonly binOnPath?: (bin: string, platform?: string) => boolean;
+}
+export declare function isStub(entry: {
+    readonly stub?: boolean;
+}): boolean;
+export declare function isToolSupported(entry: {
+    readonly tools: readonly string[];
+}, installedTools: ReadonlySet<string>): boolean;
+export declare function supportsPlatform(entry: {
+    readonly platform: readonly string[];
+}, platform: string | undefined): boolean;
+export declare function isModelCompatible(entry: {
+    readonly minCapabilityProfile?: string;
+}, activeProfile: CapabilityProfile | undefined): boolean;
+export declare function resolveSkillState(entry: SkillStateEntry, inputs?: SkillStateInputs): Promise<SkillState>;

package/dist-lib/lib/tools/skills/skill-state.js

@@ -0,0 +1,117 @@
+import { credentialRecord, isCredentialExpired } from "./auth-resolver.js";
+import { parseToolGrant } from "./tool-grants.js";
+import { missingBins } from "./bin-check.js";
+import { credentialSlots } from "./credential-slots.js";
+import { requiredSettings } from "./skill-settings.js";
+import { isCredentialRejected } from "./credential-health.js";
+import { isObsidianVaultPath, isSandboxedWorkbenchInstall, OBSIDIAN_SKILL_NAME, OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY, obsidianCliState, obsidianInstallState } from "./obsidian-readiness.js";
+import { isCapabilityProfile, meetsMinCapabilityProfile } from "../../models/model-catalog.js";
+import { SKILL_STATE, isAvailableState } from "./skill-state-constants.js";
+export { SKILL_STATE, isAvailableState };
+export function isStub(entry) {
+    return entry.stub === true;
+}
+export function isToolSupported(entry, installedTools) {
+    return entry.tools.every((name) => installedTools.has(parseToolGrant(name).name));
+}
+export function supportsPlatform(entry, platform) {
+    return !platform || entry.platform.includes(platform);
+}
+export function isModelCompatible(entry, activeProfile) {
+    const required = entry.minCapabilityProfile;
+    if (!required || activeProfile === undefined || !isCapabilityProfile(required))
+        return true;
+    return meetsMinCapabilityProfile(activeProfile, required);
+}
+export async function resolveSkillState(entry, inputs = {}) {
+    try {
+        if (!supportsPlatform(entry, inputs.platform))
+            return SKILL_STATE.unsupported;
+        if (isStub(entry))
+            return SKILL_STATE.disabled;
+        if (!isModelCompatible(entry, inputs.activeProfile))
+            return SKILL_STATE.incompatibleModel;
+        const bins = entry.requires?.bins ?? [];
+        if (entry.name === OBSIDIAN_SKILL_NAME) {
+            const vault = inputs.credentialStore
+                ? credentialRecord(await inputs.credentialStore(OBSIDIAN_VAULT_PATH_CREDENTIAL_KEY, {
+                    agentId: inputs.agentId,
+                    skills: [entry.name]
+                }))
+                : null;
+            if (vault && isObsidianVaultPath(vault.token))
+                return SKILL_STATE.ready;
+            if (isSandboxedWorkbenchInstall())
+                return SKILL_STATE.needsSetup;
+        }
+        let missing = bins.length > 0 ? missingBins(bins, inputs.platform, inputs.binOnPath) : [];
+        if (entry.name === OBSIDIAN_SKILL_NAME) {
+            const cli = obsidianCliState(inputs.platform, inputs.obsidianProbe);
+            if (cli === 'enabled' &&
+                missing.includes('obsidian') &&
+                obsidianInstallState(inputs.platform, inputs.obsidianProbe) === 'installed') {
+                missing = missing.filter((bin) => bin !== 'obsidian');
+            }
+            if (missing.length === 0 && cli === 'disabled')
+                return SKILL_STATE.needsSetup;
+        }
+        if (missing.length > 0) {
+            return SKILL_STATE.needsSetup;
+        }
+        if (inputs.binVersions &&
+            Object.keys(entry.requires?.binMinVersions ?? {}).some((bin) => inputs.binVersions?.get(bin) === 'too-old')) {
+            return SKILL_STATE.outdated;
+        }
+        const required = requiredSettings(entry);
+        if (required.length > 0) {
+            const settings = inputs.settingsStore
+                ? await inputs.settingsStore(entry.name, inputs.agentId)
+                : {};
+            if (required.some((key) => !settings[key]))
+                return SKILL_STATE.needsSetup;
+        }
+        const slots = credentialSlots(entry);
+        if (slots.length === 0)
+            return SKILL_STATE.ready;
+        const isRejected = inputs.rejected
+            ? (key) => inputs.rejected.has(key)
+            : (key) => isCredentialRejected(key, inputs.agentId, entry.name);
+        const store = inputs.credentialStore;
+        if (!store)
+            return SKILL_STATE.needsSetup;
+        const records = new Map(await Promise.all([...new Set(slots.flat())].map(async (key) => [
+            key,
+            credentialRecord(await store(key, { agentId: inputs.agentId, skills: [entry.name] }))
+        ])));
+        let disconnected = false;
+        let needsSetup = false;
+        for (const slot of slots) {
+            let healthy = false;
+            let bad = false;
+            for (const key of slot) {
+                const record = records.get(key);
+                const expired = !!record && isCredentialExpired(record);
+                if (record && !isRejected(key) && !expired) {
+                    healthy = true;
+                    break;
+                }
+                if (isRejected(key) || expired)
+                    bad = true;
+            }
+            if (healthy)
+                continue;
+            if (bad)
+                disconnected = true;
+            else
+                needsSetup = true;
+        }
+        if (disconnected)
+            return SKILL_STATE.disconnected;
+        if (needsSetup)
+            return SKILL_STATE.needsSetup;
+        return SKILL_STATE.ready;
+    }
+    catch {
+        return SKILL_STATE.failed;
+    }
+}

package/dist-lib/lib/tools/skills/tool-grants.d.ts

@@ -0,0 +1,5 @@
+export interface ToolGrant {
+    name: string;
+    scope: string | null;
+}
+export declare function parseToolGrant(entry: string): ToolGrant;

package/dist-lib/lib/tools/skills/tool-grants.js

@@ -0,0 +1,14 @@
+const GRANT_RE = /^([\w-]+)\((.*)\)$/;
+export function parseToolGrant(entry) {
+    const trimmed = entry.trim();
+    const match = GRANT_RE.exec(trimmed);
+    if (!match)
+        return { name: trimmed, scope: null };
+    const name = match[1] ?? '';
+    const scope = (match[2] ?? '').trim();
+    if (!name)
+        return { name: trimmed, scope: null };
+    if (!scope)
+        return { name, scope: null };
+    return { name, scope };
+}

package/dist-lib/lib/tools/toolsets.d.ts

@@ -0,0 +1,8 @@
+export declare const TOOLSETS: readonly ["web-search", "knowledge", "files", "exec", "http-request", "mcp-call"];
+export type Toolset = (typeof TOOLSETS)[number];
+export declare function asToolset(value?: string | null): Toolset | null;
+export interface ToolsetScoped {
+    toolset?: string | null;
+}
+export declare function permittedTools<T extends ToolsetScoped>(tools: ReadonlyArray<T>, disabled?: ReadonlyArray<string> | null): T[];
+export declare function toolsetEnabled(toolset: Toolset, disabled?: ReadonlyArray<string> | null): boolean;

package/dist-lib/lib/tools/toolsets.js

@@ -0,0 +1,20 @@
+export const TOOLSETS = [
+    'web-search',
+    'knowledge',
+    'files',
+    'exec',
+    'http-request',
+    'mcp-call'
+];
+export function asToolset(value) {
+    return TOOLSETS.find((toolset) => toolset === value) ?? null;
+}
+export function permittedTools(tools, disabled) {
+    if (!disabled?.length)
+        return [...tools];
+    const off = new Set(disabled);
+    return tools.filter((tool) => !tool.toolset || !off.has(tool.toolset));
+}
+export function toolsetEnabled(toolset, disabled) {
+    return !disabled?.includes(toolset);
+}

package/dist-lib/lib/tools/url-guard.d.ts

@@ -0,0 +1,8 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+export type HostResolver = (hostname: string) => Promise<readonly string[]>;
+export interface OutboundUrlCheck {
+    readonly blocked: string | null;
+    readonly addresses?: readonly string[];
+}
+export declare function checkOutboundHost(url: URL): string | null;
+export declare function resolveOutboundUrl(url: URL, resolveHost?: HostResolver, signal?: BareAbortSignal): Promise<OutboundUrlCheck>;