@pikku/inspector 0.12.112 → 0.12.114

package/dist/add/add-pikku-studio.d.ts

@@ -8,8 +8,10 @@ import type { InspectorState, InspectorLogger } from '../types.js';
  */
 export declare function addPikkuStudio(node: ts.Node, state: InspectorState, logger: InspectorLogger): void;
 /**
- * The checks on `definePlugin` that need the whole package: every title is a
- * key in the addon's `messages/en.json` (a key missing from another locale is
- * a warning), and every nav badge names one of the addon's functions.
+ * The checks on `definePlugin` that need the whole package: every title, and
+ * every agent's frontmatter title and description, is a key in the addon's
+ * `messages/en.json` (a key missing from another locale is a warning), every
+ * nav badge names one of the addon's functions, and a `files` list in the
+ * package.json publishes the agents/ and skills/ the addon has.
  */
 export declare function validatePikkuStudio(logger: InspectorLogger, state: InspectorState): void;

package/dist/add/add-pikku-studio.js

@@ -1,5 +1,5 @@
 import * as ts from 'typescript';
-import { existsSync, readFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { dirname, join } from 'path';
 import { ErrorCode } from '../error-codes.js';
 const SCOPES = ['studio', 'team', 'project'];
@@ -110,6 +110,8 @@ const readScreen = (element, fail) => {
     let scopes;
     let component;
     let app;
+    let agent;
+    let defaultChat;
     let ok = true;
     for (const field of element.properties) {
         const key = propName(field);
@@ -136,6 +138,10 @@ const readScreen = (element, fail) => {
             read = replaces = booleanLiteral(value);
         else if (key === 'needsApp')
             read = needsApp = booleanLiteral(value);
+        else if (key === 'defaultChat')
+            read = defaultChat = booleanLiteral(value);
+        else if (key === 'agent')
+            read = agent = ts.isStringLiteral(value) ? value.text : undefined;
         else if (key === 'layout')
             read = layout = oneOf(value, ['bare']);
         else if (key === 'scopes') {
@@ -182,6 +188,8 @@ const readScreen = (element, fail) => {
         ...(needsApp !== undefined ? { needsApp } : {}),
         ...(layout ? { layout } : {}),
         ...(scopes ? { scopes } : {}),
+        ...(agent !== undefined ? { agent } : {}),
+        ...(defaultChat !== undefined ? { defaultChat } : {}),
         ...(component ? { component } : { app: app }),
     };
 };
@@ -195,7 +203,8 @@ export function addPikkuStudio(node, state, logger) {
     if (!ts.isCallExpression(node))
         return;
     const { expression, arguments: args } = node;
-    if (!ts.isIdentifier(expression) || expression.text !== 'definePlugin' && expression.text !== 'pikkuStudio')
+    if (!ts.isIdentifier(expression) ||
+        (expression.text !== 'definePlugin' && expression.text !== 'pikkuStudio'))
         return;
     const [firstArg] = args;
     if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
@@ -259,6 +268,55 @@ const packageRoot = (file) => {
         dir = parent;
     }
 };
+const AGENT_NAME = /^[a-z][a-z0-9-]*$/;
+const STUDIO_AGENT = /^studio:[a-z][a-z0-9-]*$/;
+/** The text of a file that exists and is not blank, else undefined. */
+const readNonEmpty = (file) => {
+    try {
+        if (!statSync(file).isFile())
+            return undefined;
+        const text = readFileSync(file, 'utf-8');
+        return text.trim() === '' ? undefined : text;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The `key: value` lines of a leading `---` block; undefined when there is none. */
+const readFrontmatter = (text) => {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return undefined;
+    const fields = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const pair = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
+        if (!pair)
+            continue;
+        fields[pair[1]] = pair[2].replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return fields;
+};
+/**
+ * The package's `files` list, or undefined when it has none: what npm then
+ * publishes depends on `.npmignore` or `.gitignore`, which are not read here.
+ */
+const packageFiles = (root) => {
+    const files = readCatalog(join(root, 'package.json'))?.files;
+    return Array.isArray(files)
+        ? files.filter((entry) => typeof entry === 'string')
+        : undefined;
+};
+const filesInclude = (files, dir) => files.some((entry) => entry === dir || entry === `${dir}/` || entry.startsWith(`${dir}/`));
+/** Whether the package has a `skills/<name>/SKILL.md`. */
+const hasSkills = (root) => {
+    const dir = join(root, 'skills');
+    try {
+        return readdirSync(dir, { withFileTypes: true }).some((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, 'SKILL.md')));
+    }
+    catch {
+        return false;
+    }
+};
 const readCatalog = (file) => {
     try {
         return JSON.parse(readFileSync(file, 'utf-8'));
@@ -268,40 +326,101 @@ const readCatalog = (file) => {
     }
 };
 /**
- * The checks on `definePlugin` that need the whole package: every title is a
- * key in the addon's `messages/en.json` (a key missing from another locale is
- * a warning), and every nav badge names one of the addon's functions.
+ * The checks on `definePlugin` that need the whole package: every title, and
+ * every agent's frontmatter title and description, is a key in the addon's
+ * `messages/en.json` (a key missing from another locale is a warning), every
+ * nav badge names one of the addon's functions, and a `files` list in the
+ * package.json publishes the agents/ and skills/ the addon has.
  */
 export function validatePikkuStudio(logger, state) {
     const studio = state.studio;
     if (!studio)
         return;
-    const keys = [studio.title, ...studio.screens.map((screen) => screen.title)];
+    const keys = new Set([
+        studio.title,
+        ...studio.screens.map((screen) => screen.title),
+    ]);
     const root = packageRoot(studio.file);
+    const files = root ? packageFiles(root) : undefined;
     const messagesDir = root ? join(root, 'messages') : undefined;
     const en = messagesDir ? readCatalog(join(messagesDir, 'en.json')) : undefined;
-    for (const key of new Set(keys)) {
+    for (const key of keys) {
         if (!en || !Object.hasOwn(en, key)) {
             logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `definePlugin uses the message key '${key}', which is missing from the addon's messages/en.json`);
         }
     }
+    for (const screen of studio.screens) {
+        const agent = screen.agent;
+        if (agent !== undefined) {
+            let agentValid = true;
+            const invalid = (reason) => {
+                agentValid = false;
+                logger.critical(ErrorCode.STUDIO_SCREEN_AGENT_INVALID, `Screen '${screen.path}' has the agent '${agent}', ${reason}`);
+            };
+            if (agent.startsWith('studio:')) {
+                // An agent Studio ships: pikku cannot see it, so only the format is checked.
+                if (!STUDIO_AGENT.test(agent)) {
+                    invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+                }
+            }
+            else if (!AGENT_NAME.test(agent)) {
+                invalid("which is not a valid agent: use a name for an agent the addon ships (lowercase letters, digits and hyphens, starting with a letter) or 'studio:<name>' for one Studio ships");
+            }
+            else {
+                const text = root
+                    ? readNonEmpty(join(root, 'agents', `${agent}.md`))
+                    : undefined;
+                const fields = text === undefined ? undefined : readFrontmatter(text);
+                if (text === undefined) {
+                    invalid(`but the addon has no non-empty agents/${agent}.md`);
+                }
+                else if (!fields) {
+                    invalid(`whose agents/${agent}.md has no frontmatter; it needs a title and a description`);
+                }
+                else {
+                    for (const field of ['title', 'description']) {
+                        const key = fields[field];
+                        if (!key) {
+                            invalid(`whose agents/${agent}.md frontmatter has no ${field}; it must be a message key`);
+                            continue;
+                        }
+                        keys.add(key);
+                        if (!en || !Object.hasOwn(en, key)) {
+                            logger.critical(ErrorCode.STUDIO_MESSAGE_KEY_MISSING, `definePlugin uses the message key '${key}', which is missing from the addon's messages/en.json`);
+                        }
+                        else if (field === 'title')
+                            screen.agentTitle = key;
+                        else
+                            screen.agentDescription = key;
+                    }
+                }
+            }
+            if (agentValid &&
+                !agent.startsWith('studio:') &&
+                files &&
+                !filesInclude(files, 'agents')) {
+                logger.critical(ErrorCode.STUDIO_PACKAGE_FILES_MISSING, `Screen '${screen.path}' has the agent '${agent}', but package.json "files" does not list agents/; add "agents" to it so the published addon ships the agent`);
+            }
+        }
+        const badge = screen.nav?.badge;
+        if (badge !== undefined && !state.functions.meta[badge]) {
+            logger.critical(ErrorCode.STUDIO_BADGE_FUNCTION_NOT_FOUND, `Screen '${screen.path}' has the nav badge '${badge}', which names no function in this addon`);
+        }
+    }
+    if (root && files && !filesInclude(files, 'skills') && hasSkills(root)) {
+        logger.critical(ErrorCode.STUDIO_PACKAGE_FILES_MISSING, `The addon ships skills/ but package.json "files" does not list it; add "skills" to it so the published addon ships its skills`);
+    }
     if (messagesDir && existsSync(messagesDir)) {
         const locales = readdirSync(messagesDir)
             .filter((name) => name.endsWith('.json') && name !== 'en.json')
             .sort();
         for (const name of locales) {
             const catalog = readCatalog(join(messagesDir, name)) ?? {};
-            for (const key of new Set(keys)) {
+            for (const key of keys) {
                 if (!Object.hasOwn(catalog, key)) {
                     logger.warn(`definePlugin uses the message key '${key}', which is missing from the addon's messages/${name}`);
                 }
             }
         }
     }
-    for (const screen of studio.screens) {
-        const badge = screen.nav?.badge;
-        if (badge !== undefined && !state.functions.meta[badge]) {
-            logger.critical(ErrorCode.STUDIO_BADGE_FUNCTION_NOT_FOUND, `Screen '${screen.path}' has the nav badge '${badge}', which names no function in this addon`);
-        }
-    }
 }

package/dist/add/add-wire-addon.d.ts

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import type { InspectorState, InspectorLogger } from '../types.js';
+export declare function parseStringArray(node: ts.Expression): string[] | undefined;
 /**
  * Detect wireAddon({ name: '...', package: '...' }) call expressions and
  * populate state.rpc.wireAddonDeclarations and state.rpc.usedAddons.

package/dist/add/add-wire-addon.js

@@ -1,6 +1,6 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
-function parseStringArray(node) {
+export function parseStringArray(node) {
     if (!ts.isArrayLiteralExpression(node))
         return undefined;
     const values = [];

package/dist/add/add-wire-remote-addon.js

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
+import { parseStringArray } from './add-wire-addon.js';
 import { parseRemoteAddonPackage } from '../utils/remote-addon-sdk.js';
 /**
  * Detect wireRemoteAddon({ name: '...', package: '...' }) call expressions and
@@ -27,6 +28,7 @@ export function addWireRemoteAddon(node, state, logger) {
     let hasAuth = false;
     let authCredentialId;
     let authSecretId;
+    let local;
     for (const prop of firstArg.properties) {
         if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
             continue;
@@ -40,6 +42,42 @@ export function addWireRemoteAddon(node, state, logger) {
                 pkg = prop.initializer.text;
             }
         }
+        else if (key === 'local' &&
+            ts.isObjectLiteralExpression(prop.initializer)) {
+            let localPackage;
+            let ui;
+            let contributors;
+            for (const localProp of prop.initializer.properties) {
+                if (!ts.isPropertyAssignment(localProp) ||
+                    !ts.isIdentifier(localProp.name))
+                    continue;
+                const localKey = localProp.name.text;
+                if (localKey === 'package' &&
+                    ts.isStringLiteral(localProp.initializer)) {
+                    localPackage = localProp.initializer.text;
+                }
+                else if (localKey === 'ui' &&
+                    localProp.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                    ui = true;
+                }
+                else if (localKey === 'contributors') {
+                    contributors = parseStringArray(localProp.initializer);
+                    if (contributors === undefined) {
+                        logger.critical(ErrorCode.ADDON_CONTRIBUTORS_NOT_STATIC, `wireRemoteAddon's local.contributors must be an array of string literals, got: ${localProp.initializer.getText()}`);
+                    }
+                }
+            }
+            if (localPackage) {
+                local = {
+                    package: localPackage,
+                    ...(ui ? { ui } : {}),
+                    ...(contributors ? { contributors } : {}),
+                };
+            }
+            else {
+                logger.critical(ErrorCode.REMOTE_ADDON_PACKAGE_NOT_STATIC, `wireRemoteAddon's local.package must be a string literal, got: ${prop.initializer.getText()}`);
+            }
+        }
         else if (key === 'auth' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
             hasAuth = true;
@@ -83,6 +121,7 @@ export function addWireRemoteAddon(node, state, logger) {
         hasAuth,
         authCredentialId,
         authSecretId,
+        ...(local ? { local } : {}),
     });
     state.rpc.usedAddons.add(name);
     state.rpc.wireAddonFiles.add(node.getSourceFile().fileName);

package/dist/error-codes.d.ts

@@ -57,6 +57,8 @@ export declare enum ErrorCode {
     ADDON_CONTRIBUTORS_NOT_STATIC = "PKU362",
     ADDON_CONTRIBUTOR_UNKNOWN = "PKU363",
     ADDON_LEGACY_CONTRIBUTORS = "PKU364",
+    STUDIO_SCREEN_AGENT_INVALID = "PKU365",
+    STUDIO_PACKAGE_FILES_MISSING = "PKU366",
     DB_COLUMN_NAME_TYPE_CONTRADICTION = "PKU480",
     DB_JSON_COLUMN_UNTYPED = "PKU481",
     DB_FORMAT_ON_NON_STRING = "PKU482",

package/dist/error-codes.js

@@ -60,6 +60,8 @@ export var ErrorCode;
     ErrorCode["ADDON_CONTRIBUTORS_NOT_STATIC"] = "PKU362";
     ErrorCode["ADDON_CONTRIBUTOR_UNKNOWN"] = "PKU363";
     ErrorCode["ADDON_LEGACY_CONTRIBUTORS"] = "PKU364";
+    ErrorCode["STUDIO_SCREEN_AGENT_INVALID"] = "PKU365";
+    ErrorCode["STUDIO_PACKAGE_FILES_MISSING"] = "PKU366";
     // Database schema codegen warnings
     ErrorCode["DB_COLUMN_NAME_TYPE_CONTRADICTION"] = "PKU480";
     ErrorCode["DB_JSON_COLUMN_UNTYPED"] = "PKU481";

package/dist/types.d.ts

@@ -548,6 +548,12 @@ export type StudioScreenMeta = {
     needsApp?: boolean;
     layout?: 'bare';
     scopes?: string[];
+    agent?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentTitle?: string;
+    /** Message key from the agent file's frontmatter, filled by validation. */
+    agentDescription?: string;
+    defaultChat?: boolean;
 } & ({
     component: string;
     app?: undefined;
@@ -767,6 +773,16 @@ export interface InspectorState {
             auth?: boolean;
             tags?: string[];
             scopes?: string[];
+            /**
+             * wireRemoteAddon: a package installed in this project that carries the
+             * screens and contributors for this name, when they live apart from the
+             * contract package. `ui` and `contributors` are read from it.
+             */
+            local?: {
+                package: string;
+                ui?: boolean;
+                contributors?: string[];
+            };
             /** True when declared via `wireRemoteAddon` — import the addon's `.remote.gen` map, not `.internal.gen` */
             remote?: boolean;
             /**

package/dist/utils/load-addon-functions-meta.js

@@ -279,6 +279,27 @@ const recordDeclaredUses = (logger, namespace, decl, dirs) => {
             : `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
     }
 };
+const recordAddonScreens = async (logger, state, require, namespace, packageName, scopes) => {
+    let manifest;
+    try {
+        manifest = await loadStudioMeta(require, packageName);
+    }
+    catch (e) {
+        logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${packageName} could not be read: ${e instanceof Error ? e.message : e}`);
+        return;
+    }
+    if (!manifest || manifest.screens.length === 0) {
+        logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${packageName} declares no screens. Add a definePlugin call to the package, or drop ui.`);
+        return;
+    }
+    ;
+    (state.addonStudio ??= {})[namespace] = {
+        ...manifest,
+        scopes: [
+            ...new Set([...(manifest.scopes ?? []), ...(scopes ?? [])]),
+        ].sort(),
+    };
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -291,6 +312,16 @@ export async function loadAddonFunctionsMeta(logger, state) {
             if (decl.range) {
                 await loadRemoteAddonSdkMeta(state, namespace, decl.package, decl.range);
             }
+            if (decl.local) {
+                const dirs = addonResolutionDirs(state.rootDir, decl.file);
+                const require = createAddonResolver(dirs);
+                if (decl.local.contributors && decl.local.contributors.length > 0) {
+                    await recordOptedInContributors(logger, state, require, namespace, decl.local.package, decl.local.contributors);
+                }
+                if (decl.local.ui) {
+                    await recordAddonScreens(logger, state, require, namespace, decl.local.package, undefined);
+                }
+            }
             continue;
         }
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
@@ -304,30 +335,7 @@ export async function loadAddonFunctionsMeta(logger, state) {
                 logger.critical(ErrorCode.ADDON_LEGACY_CONTRIBUTORS, `${decl.package} still declares "pikku.contributors" in its package.json, which is no longer read. Remove it, register the contributors with defineContributors in the addon's source, and opt in with wireAddon('${namespace}', { contributors: [...] }). See docs/contributors.md.`);
             }
             if (decl.ui) {
-                let manifest;
-                let unreadable = false;
-                try {
-                    manifest = await loadStudioMeta(require, decl.package);
-                }
-                catch (e) {
-                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${decl.package} could not be read: ${e instanceof Error ? e.message : e}`);
-                    unreadable = true;
-                }
-                if (unreadable) {
-                    // reported above; the addon's functions and scopes still load
-                }
-                else if (!manifest || manifest.screens.length === 0) {
-                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a definePlugin call to the package, or drop ui.`);
-                }
-                else {
-                    ;
-                    (state.addonStudio ??= {})[namespace] = {
-                        ...manifest,
-                        scopes: [
-                            ...new Set([...(manifest.scopes ?? []), ...(decl.scopes ?? [])]),
-                        ].sort(),
-                    };
-                }
+                await recordAddonScreens(logger, state, require, namespace, decl.package, decl.scopes);
             }
             // Verbose first. `description` is one of the fields stripped from the
             // minimal copy, and it is what an addon's function is offered to a model

package/dist/utils/serialize-inspector-state.d.ts

@@ -199,6 +199,11 @@ export interface SerializableInspectorState {
                 file?: string;
                 rpcEndpoint?: string;
                 remote?: boolean;
+                local?: {
+                    package: string;
+                    ui?: boolean;
+                    contributors?: string[];
+                };
                 hasAuth?: boolean;
                 authCredentialId?: string;
                 authSecretId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.112",
+  "version": "0.12.114",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -70,10 +70,10 @@
     "zod": "^4.6.7"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.148"
+    "@pikku/core": "^0.12.151"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.148",
+    "@pikku/core": "^0.12.151",
     "@types/node": "^26.6.5"
   },
   "engines": {