@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/commands/skills-cli/index.js

@@ -134,11 +134,24 @@ export function registerSkillsCommands(program) {
         const all = hub.listWithIntegrity();
         const shown = opts.all ? all : all.filter((s) => s.enabled !== false);
         const health = buildSkillListHealth(all, shown);
-        const usableCount = all.filter((skill) => skill.enabled !== false && skill.integrityOk).length;
+        const { readLocalSkillInventory } = await import('../../skills/local-inventory.js');
+        const inventory = await readLocalSkillInventory(all);
+        const availableSkills = inventory.entries.filter((skill) => skill.available);
+        const usableCount = availableSkills.filter((skill) => skill.source === 'hub').length;
         if (opts.json) {
-            console.log(JSON.stringify({ count: shown.length, health, total: all.length, skills: shown }, null, 2));
+            console.log(JSON.stringify({ availableSkills, availableCount: availableSkills.length,
+                unavailableSkills: inventory.entries.filter((skill) => !skill.available),
+                discoveryErrors: inventory.errors,
+                count: shown.length, health, total: all.length, skills: shown }, null, 2));
             return;
         }
+        console.log(`\nAvailable local skills (${availableSkills.length}):`);
+        for (const skill of availableSkills) {
+            console.log(`  + ${skill.name} (${skill.source})${skill.description ? ` — ${skill.description}` : ''}`);
+        }
+        if (inventory.errors.length > 0) {
+            console.log(`\n${inventory.errors.length} skill file(s) could not be loaded; use --json for details.`);
+        }
         if (shown.length === 0) {
             if (all.length === 0) {
                 const { getBundledSkillsPath } = await import('../../skills/index.js');
@@ -280,26 +293,36 @@ export function registerSkillsCommands(program) {
     });
     skills
         .command('usage')
-        .description('Show local usage telemetry, most-used first')
+        .description('Show local usage telemetry: hub invocations and view/use activity of every skill')
         .option('--json', 'output JSON')
         .action(async (opts) => {
         const { getSkillsHub } = await import('../../skills/hub.js');
+        const { listSkillActivity } = await import('../../skills/skill-usage-store.js');
         const summary = getSkillsHub().usageSummary();
+        const activity = listSkillActivity();
         if (opts.json) {
-            console.log(JSON.stringify({ count: summary.length, skills: summary }, null, 2));
+            console.log(JSON.stringify({ count: summary.length, skills: summary, activityCount: activity.length, activity }, null, 2));
             return;
         }
-        if (summary.length === 0) {
+        if (summary.length === 0 && activity.length === 0) {
             console.log('No skill usage recorded yet.');
             return;
         }
-        console.log('\nSkill usage (most used first):');
-        for (const skill of summary) {
-            const u = skill.usage;
-            const avg = u.averageDurationMs !== undefined ? `, avg ${Math.round(u.averageDurationMs)}ms` : '';
-            console.log(`  ${skill.name}: ${u.invocationCount} run(s), ${u.successCount} ok / ${u.failureCount} fail${avg}`);
-            if (u.lastError)
-                console.log(`      last error: ${u.lastError}`);
+        if (summary.length > 0) {
+            console.log('\nSkill usage (most used first):');
+            for (const skill of summary) {
+                const u = skill.usage;
+                const avg = u.averageDurationMs !== undefined ? `, avg ${Math.round(u.averageDurationMs)}ms` : '';
+                console.log(`  ${skill.name}: ${u.invocationCount} run(s), ${u.successCount} ok / ${u.failureCount} fail${avg}`);
+                if (u.lastError)
+                    console.log(`      last error: ${u.lastError}`);
+            }
+        }
+        if (activity.length > 0) {
+            console.log('\nSkill activity (most recent first):');
+            for (const entry of activity) {
+                console.log(`  ${entry.skill}: ${entry.viewCount} view(s), ${entry.useCount} use(s), last ${entry.lastActivityAt}`);
+            }
         }
         console.log('');
     });

package/dist/commands/slash/builtin-commands.js

@@ -342,9 +342,12 @@ const devCommands = [
     {
         name: 'debug-issue',
         description: 'Help debug a code issue',
-        prompt: `Help debug the described issue:
+        // A bare /debug-issue used to send "the described issue" with nothing
+        // described; the prompt now stands on its own with or without a symptom.
+        prompt: `Debug a problem in this project.
+Reported symptom (empty if the user gave none): $ARGUMENTS
 
-1. Gather information about the problem
+1. Gather information about the problem. Without a reported symptom, start from the working tree: git status --short, git diff for unstaged changes, git diff --cached for staged changes, then run the project's test script if one exists
 2. Analyze relevant code and logs
 3. Identify potential causes
 4. Suggest debugging steps
@@ -352,7 +355,10 @@ const devCommands = [
 
 Be systematic and thorough in your analysis.`,
         filePath: '',
-        isBuiltin: true
+        isBuiltin: true,
+        arguments: [
+            { name: 'symptom', description: 'Error message or behaviour to debug (optional)', required: false }
+        ]
     },
     {
         name: 'refactor',
@@ -1309,6 +1315,13 @@ const agentControlCommands = [
         filePath: '',
         isBuiltin: true
     },
+    {
+        name: 'resources',
+        description: 'List declared resources (RagChat, GPU, storage…) and observation freshness — read-only, no probe',
+        prompt: '__RESOURCES__',
+        filePath: '',
+        isBuiltin: true
+    },
     {
         name: 'new',
         description: 'Start a new conversation, optionally switching to a different model',

package/dist/commands/slash/index.d.ts

@@ -3,5 +3,7 @@
  *
  * Exports types, built-in commands, and utilities for the slash command system.
  */
-export type { SlashCommand, SlashCommandArgument, SlashCommandResult, SlashCommandCategory, CategorizedSlashCommand } from './types.js';
+export type { SlashCommand, SlashCommandArgument, SlashCommandResult, SlashCommandCategory, CategorizedSlashCommand, SlashSurface, SlashAvailability } from './types.js';
 export { builtinCommands, getCommandsByCategory } from './builtin-commands.js';
+export { CHANNEL_SLASH_SURFACES, channelPlatformsFor, COWORK_TOKEN_SURFACES, COWORK_UNAVAILABLE_REASON, coworkHeadlessAllowlist, coworkUiEffectTokens, isEngineToken, resolveSlashAvailability, withAvailability, } from './surfaces.js';
+export type { ChannelSlashSpec, CoworkTokenMode, SlashCommandWithAvailability } from './surfaces.js';

package/dist/commands/slash/index.js

@@ -5,4 +5,6 @@
  */
 // Built-in commands
 export { builtinCommands, getCommandsByCategory } from './builtin-commands.js';
+// Per-surface availability (single declaration for CLI, Cowork and the wiki)
+export { CHANNEL_SLASH_SURFACES, channelPlatformsFor, COWORK_TOKEN_SURFACES, COWORK_UNAVAILABLE_REASON, coworkHeadlessAllowlist, coworkUiEffectTokens, isEngineToken, resolveSlashAvailability, withAvailability, } from './surfaces.js';
 //# sourceMappingURL=index.js.map

package/dist/commands/slash/surfaces.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Per-surface availability of slash commands (comparatif plan P4).
+ *
+ * Single declaration read by the CLI catalog, the Cowork main process (which
+ * derives its headless allowlist from it) and the generated slash wiki.
+ *
+ * Rules:
+ * - CLI: every built-in is available unless a command declares otherwise.
+ * - Cowork, DEFAULT-DENY for engine tokens (`__FOO__` prompts): a token is only
+ *   pilotable from Cowork when it is declared below either as `headless` (runs
+ *   through `executeHeadlessSlashToken` with this allowlist) or `ui_effect`
+ *   (Cowork renders a native panel/effect). Undeclared tokens are unavailable
+ *   with an explicit reason. Natural-language prompt commands are forwarded as
+ *   prompts and are therefore available.
+ * - A command-level `surfaces` declaration can only RESTRICT a surface (hidden
+ *   or unavailable); it never widens the Cowork token allowlist.
+ */
+import type { SlashAvailability, SlashCommand, SlashSurface } from './types.js';
+export type CoworkTokenMode = 'headless' | 'ui_effect';
+/**
+ * Tokens Cowork can pilot. `headless` entries are safe to run from the Cowork
+ * main process today (read-only info or session-scoped goal state); see the
+ * rationale kept in cowork/src/main/commands/slash-command-bridge.ts.
+ */
+export declare const COWORK_TOKEN_SURFACES: Readonly<Record<string, CoworkTokenMode>>;
+/**
+ * Bot commands expected on each messaging platform (the `channels` surface).
+ * This is the single declaration read by `src/channels/slash-parity.ts`.
+ * A name that matches a builtin is the same command reached from a chat
+ * platform; `channelOnly` marks bot-only commands with no terminal builtin.
+ */
+export interface ChannelSlashSpec {
+    name: string;
+    description: string;
+    required?: boolean;
+    channelOnly?: boolean;
+}
+export declare const CHANNEL_SLASH_SURFACES: Readonly<Record<string, readonly ChannelSlashSpec[]>>;
+/** Platforms whose bot exposes this command; a `channels` restriction on the command removes it everywhere. */
+export declare function channelPlatformsFor(command: Pick<SlashCommand, 'name' | 'surfaces'>): string[];
+export declare const COWORK_UNAVAILABLE_REASON = "not pilotable from Cowork yet \u2014 use the terminal (buddy)";
+export declare function isEngineToken(prompt: string): boolean;
+/** Tokens the Cowork main process may run headlessly (derived, never hand-maintained elsewhere). */
+export declare function coworkHeadlessAllowlist(): ReadonlySet<string>;
+export declare function coworkUiEffectTokens(): ReadonlySet<string>;
+/** Effective availability of one catalog command on one surface. */
+export declare function resolveSlashAvailability(command: Pick<SlashCommand, 'name' | 'prompt' | 'surfaces'>, surface: SlashSurface): SlashAvailability;
+export interface SlashCommandWithAvailability extends SlashCommand {
+    availability: Record<'cli' | 'cowork', SlashAvailability>;
+    /** Messaging platforms whose bot exposes the same command (from CHANNEL_SLASH_SURFACES). */
+    channelPlatforms: string[];
+}
+export declare function withAvailability(commands: readonly SlashCommand[]): SlashCommandWithAvailability[];

package/dist/commands/slash/surfaces.js

@@ -0,0 +1,177 @@
+/**
+ * Per-surface availability of slash commands (comparatif plan P4).
+ *
+ * Single declaration read by the CLI catalog, the Cowork main process (which
+ * derives its headless allowlist from it) and the generated slash wiki.
+ *
+ * Rules:
+ * - CLI: every built-in is available unless a command declares otherwise.
+ * - Cowork, DEFAULT-DENY for engine tokens (`__FOO__` prompts): a token is only
+ *   pilotable from Cowork when it is declared below either as `headless` (runs
+ *   through `executeHeadlessSlashToken` with this allowlist) or `ui_effect`
+ *   (Cowork renders a native panel/effect). Undeclared tokens are unavailable
+ *   with an explicit reason. Natural-language prompt commands are forwarded as
+ *   prompts and are therefore available.
+ * - A command-level `surfaces` declaration can only RESTRICT a surface (hidden
+ *   or unavailable); it never widens the Cowork token allowlist.
+ */
+/**
+ * Tokens Cowork can pilot. `headless` entries are safe to run from the Cowork
+ * main process today (read-only info or session-scoped goal state); see the
+ * rationale kept in cowork/src/main/commands/slash-command-bridge.ts.
+ */
+export const COWORK_TOKEN_SURFACES = Object.freeze({
+    // Headless (engine behaviour, default-deny allowlist)
+    __HELP__: 'headless',
+    __STATS__: 'headless',
+    __COST__: 'headless',
+    __TOOLS__: 'headless',
+    __WHOAMI__: 'headless',
+    __STATUS__: 'headless',
+    __FEATURES__: 'headless',
+    __HISTORY__: 'headless',
+    __LOG__: 'headless',
+    __WORKSPACE__: 'headless',
+    __DIFF__: 'headless',
+    __QUOTA__: 'headless',
+    __EXPORT_FORMATS__: 'headless',
+    __EXPORT_LIST__: 'headless',
+    __GOAL__: 'headless',
+    __SUBGOAL__: 'headless',
+    __RESOURCES__: 'headless',
+    // Native Cowork effects (panels, settings tabs, orchestrator, engine actions)
+    __CHANGE_MODEL__: 'ui_effect',
+    __SWITCH__: 'ui_effect',
+    __PLAN_MODE__: 'ui_effect',
+    __SWARM__: 'ui_effect',
+    __PARALLEL__: 'ui_effect',
+    __BATCH__: 'ui_effect',
+    __AGENTS__: 'ui_effect',
+    __FLEET__: 'ui_effect',
+    __TEAM__: 'ui_effect',
+    __LESSONS__: 'ui_effect',
+    __COMPANION__: 'ui_effect',
+    __TRACK__: 'ui_effect',
+    __CONFIG__: 'ui_effect',
+    __WORKFLOW__: 'ui_effect',
+    __PIPELINE__: 'ui_effect',
+    __PERMISSIONS__: 'ui_effect',
+    __POLICY__: 'ui_effect',
+    __APPROVALS__: 'ui_effect',
+    __ELEVATED__: 'ui_effect',
+    __BATCH_REVIEW__: 'ui_effect',
+    __SECURITY__: 'ui_effect',
+    __HOOKS__: 'ui_effect',
+    __PLUGINS__: 'ui_effect',
+    __PLUGIN__: 'ui_effect',
+    __THEME__: 'ui_effect',
+    __AVATAR__: 'ui_effect',
+    __VIM_MODE__: 'ui_effect',
+    __FAST_MODE__: 'ui_effect',
+    __DRY_RUN__: 'ui_effect',
+    __CACHE__: 'ui_effect',
+    __PROMPT_CACHE__: 'ui_effect',
+    __SELF_HEALING__: 'ui_effect',
+    __SEARCH__: 'ui_effect',
+    __SHORTCUTS__: 'ui_effect',
+    __PERSONA__: 'ui_effect',
+    __SESSIONS__: 'ui_effect',
+    __REMEMBER__: 'ui_effect',
+    __IDENTITY__: 'ui_effect',
+    __PAIRING__: 'ui_effect',
+    __VOICE__: 'ui_effect',
+    __SPEAK__: 'ui_effect',
+    __TTS__: 'ui_effect',
+    __EXPORT__: 'ui_effect',
+    __SAVE_CONVERSATION__: 'ui_effect',
+    __TEST__: 'ui_effect',
+    __THINK__: 'ui_effect',
+    __KNOWLEDGE_GRAPH__: 'ui_effect',
+    __UNDO__: 'ui_effect',
+    __REDO__: 'ui_effect',
+    __SUBAGENT__: 'ui_effect',
+    __AGENT__: 'ui_effect',
+});
+export const CHANNEL_SLASH_SURFACES = Object.freeze({
+    discord: [
+        { name: 'ask', description: 'Ask Code Buddy a question', channelOnly: true },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'think', description: 'Set reasoning depth', required: false },
+        { name: 'compact', description: 'Compact conversation context', required: false },
+        { name: 'repo', description: 'Show repository info', required: false, channelOnly: true },
+    ],
+    telegram: [
+        { name: 'ask', description: 'Ask Code Buddy a question', channelOnly: true },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'yolo', description: 'Toggle YOLO mode', required: false },
+        { name: 'repo', description: 'Show repository info', required: false, channelOnly: true },
+        { name: 'branch', description: 'Show branch info', required: false },
+    ],
+    slack: [
+        { name: 'ask', description: 'Ask Code Buddy a question', channelOnly: true },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model' },
+        { name: 'compact', description: 'Compact conversation context', required: false },
+        { name: 'think', description: 'Set reasoning depth', required: false },
+    ],
+    matrix: [
+        { name: 'ask', description: 'Ask Code Buddy a question', channelOnly: true },
+        { name: 'status', description: 'Show bot and channel status' },
+        { name: 'clear', description: 'Clear conversation history' },
+        { name: 'help', description: 'Show available commands' },
+        { name: 'model', description: 'Switch or show current model', required: false },
+    ],
+});
+/** Platforms whose bot exposes this command; a `channels` restriction on the command removes it everywhere. */
+export function channelPlatformsFor(command) {
+    const declared = command.surfaces?.channels;
+    if (declared && declared.status !== 'available')
+        return [];
+    return Object.entries(CHANNEL_SLASH_SURFACES)
+        .filter(([, specs]) => specs.some((spec) => !spec.channelOnly && spec.name === command.name))
+        .map(([platform]) => platform);
+}
+export const COWORK_UNAVAILABLE_REASON = 'not pilotable from Cowork yet — use the terminal (buddy)';
+export function isEngineToken(prompt) {
+    return prompt.length > 4 && prompt.startsWith('__') && prompt.endsWith('__');
+}
+/** Tokens the Cowork main process may run headlessly (derived, never hand-maintained elsewhere). */
+export function coworkHeadlessAllowlist() {
+    return new Set(Object.entries(COWORK_TOKEN_SURFACES).filter(([, mode]) => mode === 'headless').map(([token]) => token));
+}
+export function coworkUiEffectTokens() {
+    return new Set(Object.entries(COWORK_TOKEN_SURFACES).filter(([, mode]) => mode === 'ui_effect').map(([token]) => token));
+}
+const AVAILABLE = { status: 'available' };
+/** Effective availability of one catalog command on one surface. */
+export function resolveSlashAvailability(command, surface) {
+    const declared = command.surfaces?.[surface];
+    const restricting = declared && declared.status !== 'available' ? declared : undefined;
+    if (surface === 'cowork') {
+        if (restricting)
+            return restricting;
+        if (!isEngineToken(command.prompt))
+            return AVAILABLE;
+        return COWORK_TOKEN_SURFACES[command.prompt] ? AVAILABLE : { status: 'unavailable', reason: COWORK_UNAVAILABLE_REASON };
+    }
+    return declared ?? AVAILABLE;
+}
+export function withAvailability(commands) {
+    return commands.map((command) => ({
+        ...command,
+        availability: {
+            cli: resolveSlashAvailability(command, 'cli'),
+            cowork: resolveSlashAvailability(command, 'cowork'),
+        },
+        channelPlatforms: channelPlatformsFor(command),
+    }));
+}
+//# sourceMappingURL=surfaces.js.map

package/dist/commands/slash/types.d.ts

@@ -32,7 +32,24 @@ export interface SlashCommand {
     isBuiltin: boolean;
     /** List of arguments accepted by the command. */
     arguments?: SlashCommandArgument[];
+    /**
+     * Optional per-surface restriction (P4). Resolution lives in `surfaces.ts`;
+     * a declaration can hide or disable a command on a surface, never widen the
+     * Cowork default-deny token allowlist.
+     */
+    surfaces?: Partial<Record<SlashSurface, SlashAvailability>>;
 }
+/** Surfaces that expose slash commands. */
+export type SlashSurface = 'cli' | 'cowork' | 'channels';
+/** Availability of a command on a surface. */
+export type SlashAvailability = {
+    status: 'available';
+} | {
+    status: 'hidden';
+} | {
+    status: 'unavailable';
+    reason: string;
+};
 /**
  * Result of executing or parsing a slash command.
  */

package/dist/commands/try.d.ts

@@ -54,7 +54,7 @@ export interface RunTryDemoOptions extends ResolveTryProviderOptions {
 export interface TryCommandDependencies {
     runTryDemo?: (options: RunTryDemoOptions) => Promise<number>;
 }
-export declare const TRY_DEMO_PROMPT = "You are driving a short coding-agent demo in an empty temporary folder.\n\nExact goal:\n1. Create fizzbuzz.js in CommonJS. Export a function fizzBuzz(value) that returns the number as a string, \"Fizz\" for multiples of 3, \"Buzz\" for multiples of 5, and \"FizzBuzz\" for multiples of 15.\n2. Create fizzbuzz.test.js using node:test and node:assert/strict. Test at least 1, 3, 5, and 15.\n3. Run exactly: node --test fizzbuzz.test.js\n4. If a test fails, fix the code and run it again.\n5. Finish with a very short summary naming the two files you created and the test result.\n\nWrite everything in English. Use the file and terminal tools directly. Do not ask for any confirmation, do not install any dependency, and do not change anything outside the working folder.";
+export declare const TRY_DEMO_PROMPT = "You are driving a short coding-agent demo in an empty temporary folder.\n\nExact goal:\n1. Create fizzbuzz.js in CommonJS. Export a function fizzBuzz(value) that returns the number as a string, \"Fizz\" for multiples of 3, \"Buzz\" for multiples of 5, and \"FizzBuzz\" for multiples of 15.\n2. Create fizzbuzz.test.js using node:test and node:assert/strict. Test at least 1, 3, 5, and 15.\n3. Run exactly: node --test fizzbuzz.test.js\n4. If a test fails, fix the code and run it again.\n5. Finish with a very short summary naming the two files you created and the test result.\n\nWrite everything in English. Use the file and terminal tools with the configured permissions. Work only inside the temporary folder; no dependency installation is needed.";
 export declare const NO_TRY_PROVIDER_MESSAGE: string;
 /** Pick a coding-oriented local model without assuming one exact Ollama tag. */
 export declare function chooseOllamaModel(models: readonly string[], requested?: string): string | null;

package/dist/commands/try.js

@@ -24,7 +24,7 @@ Exact goal:
 4. If a test fails, fix the code and run it again.
 5. Finish with a very short summary naming the two files you created and the test result.
 
-Write everything in English. Use the file and terminal tools directly. Do not ask for any confirmation, do not install any dependency, and do not change anything outside the working folder.`;
+Write everything in English. Use the file and terminal tools with the configured permissions. Work only inside the temporary folder; no dependency installation is needed.`;
 export const NO_TRY_PROVIDER_MESSAGE = [
     'No free provider is ready for the demo.',
     '',

package/dist/companion/companion-identity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Companion identity resolution.
+ *
+ * Resolves who is speaking to Lisa across Telegram, PWA mobile WebSocket,
+ * and physical voice presence, and assigns a trust level:
+ * - 'owner': Full trust. Identified via Telegram allowlist/chat or PWA JWT.
+ * - 'present': Physical presence detected and robot named. Lower trust.
+ * - 'guest': Unknown / unauthenticated speaker. Fail-closed: ZERO tools.
+ *
+ * @module companion/companion-identity
+ */
+export type CompanionIdentityRole = 'owner' | 'present' | 'guest';
+export type CompanionIdentityConfidence = 'high' | 'medium' | 'none';
+export interface CompanionIdentity {
+    role: CompanionIdentityRole;
+    channel: 'telegram' | 'pwa' | 'voice' | 'channel' | 'unknown';
+    userId?: string;
+    chatId?: string;
+    confidence: CompanionIdentityConfidence;
+    reason: string;
+}
+export interface ResolveIdentityOptions {
+    channel: 'telegram' | 'pwa' | 'mobile' | 'voice' | 'channel' | string;
+    userId?: string;
+    chatId?: string;
+    senderId?: string;
+    senderUsername?: string;
+    allowedUsers?: readonly string[];
+    isVoicePresence?: boolean;
+    robotNamed?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve identity and confidence tier from incoming channel information.
+ * Pure function: takes options and env, zero global side-effects.
+ */
+export declare function resolveCompanionIdentity(options: ResolveIdentityOptions): CompanionIdentity;
+/** Check if identity is owner */
+export declare function isCompanionOwner(identity?: CompanionIdentity | null): boolean;
+/** Check if identity is at least present (owner or present) */
+export declare function isCompanionPresentOrOwner(identity?: CompanionIdentity | null): boolean;
+/** Default guest identity (fail-closed) */
+export declare const DEFAULT_GUEST_IDENTITY: CompanionIdentity;

package/dist/companion/companion-identity.js

@@ -0,0 +1,136 @@
+/**
+ * Companion identity resolution.
+ *
+ * Resolves who is speaking to Lisa across Telegram, PWA mobile WebSocket,
+ * and physical voice presence, and assigns a trust level:
+ * - 'owner': Full trust. Identified via Telegram allowlist/chat or PWA JWT.
+ * - 'present': Physical presence detected and robot named. Lower trust.
+ * - 'guest': Unknown / unauthenticated speaker. Fail-closed: ZERO tools.
+ *
+ * @module companion/companion-identity
+ */
+/**
+ * Resolve identity and confidence tier from incoming channel information.
+ * Pure function: takes options and env, zero global side-effects.
+ */
+export function resolveCompanionIdentity(options) {
+    const env = options.env ?? process.env;
+    const channelRaw = (options.channel || '').toLowerCase().trim();
+    // 1. Telegram
+    if (channelRaw === 'telegram') {
+        const alertChat = (env.CODEBUDDY_SENSORY_ALERT_CHAT ?? '').trim();
+        const allowed = new Set((options.allowedUsers ?? []).map((u) => u.trim().toLowerCase()));
+        const chatId = (options.chatId ?? '').trim();
+        const senderId = (options.senderId ?? options.userId ?? '').trim();
+        const rawUsername = (options.senderUsername ?? '').trim().toLowerCase();
+        const senderUsername = rawUsername.replace(/^@/, '');
+        const isChatAlertMatch = Boolean(alertChat && chatId && chatId === alertChat);
+        const isChatAllowedMatch = Boolean(chatId && allowed.has(chatId.toLowerCase()));
+        const isSenderIdMatch = Boolean(senderId && allowed.has(senderId.toLowerCase()));
+        const isUsernameMatch = Boolean(senderUsername && (allowed.has(senderUsername) || allowed.has(`@${senderUsername}`)));
+        if (isChatAlertMatch || isChatAllowedMatch || isSenderIdMatch || isUsernameMatch) {
+            return {
+                role: 'owner',
+                channel: 'telegram',
+                ...(senderId ? { userId: senderId } : {}),
+                ...(chatId ? { chatId } : {}),
+                confidence: 'high',
+                reason: isChatAlertMatch
+                    ? 'telegram_sensory_alert_chat_match'
+                    : isChatAllowedMatch
+                        ? 'telegram_chat_id_allowed'
+                        : isSenderIdMatch
+                            ? 'telegram_sender_id_allowed'
+                            : 'telegram_username_allowed',
+            };
+        }
+        return {
+            role: 'guest',
+            channel: 'telegram',
+            ...(chatId ? { chatId } : {}),
+            confidence: 'none',
+            reason: 'telegram_unauthorized_sender',
+        };
+    }
+    // 2. PWA (Mobile / Web)
+    if (channelRaw === 'pwa' || channelRaw === 'mobile') {
+        const userId = (options.userId ?? options.senderId ?? '').trim();
+        if (!userId) {
+            return {
+                role: 'guest',
+                channel: 'pwa',
+                confidence: 'none',
+                reason: 'pwa_missing_jwt_user_id',
+            };
+        }
+        const ownerUserId = (env.CODEBUDDY_OWNER_USER_ID ?? '').trim();
+        if (ownerUserId) {
+            if (userId === ownerUserId) {
+                return {
+                    role: 'owner',
+                    channel: 'pwa',
+                    userId,
+                    confidence: 'high',
+                    reason: 'pwa_jwt_owner_matched',
+                };
+            }
+            return {
+                role: 'guest',
+                channel: 'pwa',
+                userId,
+                confidence: 'none',
+                reason: 'pwa_jwt_user_not_owner',
+            };
+        }
+        // Default when CODEBUDDY_OWNER_USER_ID is not set:
+        // Any valid JWT issued and verified by this daemon is recognized as owner.
+        // In a single-user self-hosted installation, only the owner holds the login credentials.
+        return {
+            role: 'owner',
+            channel: 'pwa',
+            userId,
+            confidence: 'high',
+            reason: 'pwa_jwt_valid_server_token_default_owner',
+        };
+    }
+    // 3. Voice
+    if (channelRaw === 'voice') {
+        if (options.isVoicePresence === true && options.robotNamed === true) {
+            return {
+                role: 'present',
+                channel: 'voice',
+                confidence: 'medium',
+                reason: 'voice_presence_and_robot_named',
+            };
+        }
+        return {
+            role: 'guest',
+            channel: 'voice',
+            confidence: 'none',
+            reason: 'voice_unauthenticated_or_unnamed',
+        };
+    }
+    // 4. Default / unknown channel -> fail closed
+    return {
+        role: 'guest',
+        channel: 'unknown',
+        confidence: 'none',
+        reason: 'unknown_channel_fail_closed',
+    };
+}
+/** Check if identity is owner */
+export function isCompanionOwner(identity) {
+    return identity?.role === 'owner';
+}
+/** Check if identity is at least present (owner or present) */
+export function isCompanionPresentOrOwner(identity) {
+    return identity?.role === 'owner' || identity?.role === 'present';
+}
+/** Default guest identity (fail-closed) */
+export const DEFAULT_GUEST_IDENTITY = Object.freeze({
+    role: 'guest',
+    channel: 'unknown',
+    confidence: 'none',
+    reason: 'default_guest_fail_closed',
+});
+//# sourceMappingURL=companion-identity.js.map

package/dist/companion/companion-toolset.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Companion Toolset definition, authorization and execution gates.
+ *
+ * Defines which tools Lisa can use based on the interlocutor's identity tier:
+ * - 'owner': image_generate, image_edit, remind, web_search, weather, stock_quote,
+ *            understand_video, camera_analyze, recall.
+ * - 'present': same tools WITHOUT remind and WITHOUT camera (camera_analyze).
+ * - 'guest': NO tools (fail-closed, byte-identical to historical turn).
+ *
+ * Hard security invariants:
+ * - NEVER bash, shell_exec, file writing (create_file, edit, patch), MCP, fleet tools.
+ * - Circuit-breaker: CODEBUDDY_COMPANION_TOOLS_ENABLED (default: false -> 0 tools).
+ * - Surcharge: CODEBUDDY_COMPANION_TOOLS (csv list, filtered against hard constraints).
+ *
+ * @module companion/companion-toolset
+ */
+import type { CodeBuddyTool } from '../codebuddy/client.js';
+import type { ToolResult } from '../types/index.js';
+import { ConfirmationService } from '../utils/confirmation-service.js';
+import { FormalToolRegistry } from '../tools/registry/tool-registry.js';
+import type { CompanionIdentity } from './companion-identity.js';
+export declare const OWNER_COMPANION_TOOLS: readonly string[];
+export declare const PRESENT_COMPANION_TOOLS: readonly string[];
+export declare const GUEST_COMPANION_TOOLS: readonly string[];
+/** Strictly forbidden tool patterns that can NEVER be exposed to companion */
+export declare const COMPANION_FORBIDDEN_PATTERNS: readonly (string | RegExp)[];
+/**
+ * Check if a tool is strictly forbidden for the companion.
+ */
+export declare function isForbiddenCompanionTool(toolName: string): boolean;
+/**
+ * Check if companion tools are enabled via circuit-breaker.
+ * Default is FALSE (OFF).
+ */
+export declare function isCompanionToolsEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve allowed tool names for a given identity and environment.
+ */
+export declare function getCompanionToolNames(identity: CompanionIdentity, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Human-friendly waiting phrase when a slow tool starts executing.
+ */
+export declare function getCompanionToolWaitingWord(toolName: string): string | null;
+/**
+ * Get OpenAI-compatible function tool definitions for allowed companion tools.
+ */
+export declare function getCompanionToolDefinitions(identity: CompanionIdentity, options?: {
+    env?: NodeJS.ProcessEnv;
+    registry?: FormalToolRegistry;
+}): Promise<CodeBuddyTool[]>;
+export interface CompanionToolExecutionContext {
+    identity: CompanionIdentity;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    signal?: AbortSignal;
+    registry?: FormalToolRegistry;
+    confirmationService?: ConfirmationService;
+}
+/**
+ * Safely execute a companion tool call.
+ */
+export declare function executeCompanionTool(toolName: string, args: Record<string, unknown>, context: CompanionToolExecutionContext): Promise<ToolResult>;
+/**
+ * Extract image path from tool execution result if one was created/returned.
+ */
+export declare function extractImagePathFromToolResult(result: ToolResult, cwd?: string): string | undefined;