@promptbook/node 0.114.0-3 → 0.114.0-31

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationOrigin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin;

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationStatus.d.ts

@@ -1,15 +1,17 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 /**
  * Result of comparing the globally installed harness version with the newest published one.
  *
  * - `up-to-date` the newest published version is installed
  * - `outdated` an older version is installed
  * - `not-installed` the harness command is not available globally
+ * - `installed` the harness is installed and automatic update checking was disabled
  * - `unknown` the harness is installed but the newest published version could not be resolved, for example when offline
  *
  * @private internal utility of `promptbookCli`
  */
-export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'unknown';
+export type HarnessInstallationState = 'up-to-date' | 'outdated' | 'not-installed' | 'installed' | 'unknown';
 /**
  * Installation state of one CLI coding harness on the current machine.
  *
@@ -21,7 +23,7 @@ export type HarnessInstallationStatus = {
      */
     readonly definition: HarnessDefinition;
     /**
-     * Comparison of the installed version with the newest published one.
+     * Installation state, including whether the newest published version was checked.
      */
     readonly installationState: HarnessInstallationState;
     /**
@@ -32,4 +34,8 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };

package/esm/src/cli/cli-commands/common/harness/HarnessUpdatePlan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};

package/esm/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.d.ts

@@ -2,9 +2,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @private internal utility of `promptbookCli`
  */
 export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

package/esm/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessManualUpdateInstruction(status: HarnessInstallationStatus, updatePlan: HarnessUpdatePlan): string;

package/esm/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+/**
+ * Options describing where the harness command was found.
+ *
+ * @private internal utility of `resolveHarnessInstallationMethodFromPaths`
+ */
+type HarnessInstallationPaths = {
+    /**
+     * Harness whose command was located.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * Resolved path of the harness command with every symbolic link followed.
+     */
+    readonly commandPath: string;
+    /**
+     * Root directory of global npm installations or `null` when npm could not be asked for it.
+     */
+    readonly npmGlobalPrefixPath: string | null;
+};
+/**
+ * Decides how a harness command was installed from the place where it really lives.
+ *
+ * Only a command which npm owns may be updated with `npm install -g`, every other command has to be
+ * updated where it is installed, otherwise the update silently adds a second copy of the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod;
+export {};

package/esm/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Decides how one outdated CLI coding harness should be updated.
+ *
+ * The plan follows the way the harness was installed, because `npm install -g` updates only a harness
+ * which npm owns and installs a **second** copy of every other one.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessUpdatePlan(definition: HarnessDefinition, installationMethod: HarnessInstallationMethod): HarnessUpdatePlan;

package/esm/src/cli/cli-commands/common/harnessUpdateCliOptions.d.ts

@@ -0,0 +1,29 @@
+import type { Command as Program } from 'commander';
+/**
+ * Commander option bag for opting out of automatic coding-harness update checks.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdateCliOptions = {
+    readonly harnessUpdate: boolean;
+};
+/**
+ * Normalized automatic coding-harness update-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedHarnessUpdateCliOptions = {
+    readonly isHarnessUpdateCheckEnabled: boolean;
+};
+/**
+ * Registers the shared `--no-harness-update` option on a `ptbk coder` command that uses a coding harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addHarnessUpdateOption(command: Program): void;
+/**
+ * Converts the Commander harness-update flag into the normalized harness-check option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizeHarnessUpdateCliOptions(cliOptions: HarnessUpdateCliOptions): NormalizedHarnessUpdateCliOptions;

package/{umd/src/cli/cli-commands/common/harness/$askForHarnessInstallationApproval.d.ts → esm/src/cli/cli-commands/common/npm/$askForNpmPackageInstallationApproval.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Asks the user in the terminal whether the harness should be installed or updated right now.
+ * Asks the user in the terminal whether an npm package should be installed or updated now.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it reads the answer from stdin
  *
  * @returns `true` when the user confirms, `false` when the user declines or the terminal is not interactive
  * @private internal utility of `promptbookCli`
  */
-export declare function $askForHarnessInstallationApproval(question: string): Promise<boolean>;
+export declare function $askForNpmPackageInstallationApproval(question: string): Promise<boolean>;

package/{umd/src/cli/cli-commands/common/harness/$resolveLatestHarnessVersion.d.ts → esm/src/cli/cli-commands/common/npm/$resolveLatestNpmPackageVersion.d.ts}

@@ -1,10 +1,9 @@
-import type { HarnessDefinition } from './HarnessDefinition';
 /**
- * Reads the newest version of the harness published to npm.
+ * Reads the newest version of one npm package.
  *
  * Note: `$` is used to indicate that this function is not a pure function - it queries the npm registry
  *
  * @returns The newest published version or `null` when the registry could not be reached
  * @private internal utility of `promptbookCli`
  */
-export declare function $resolveLatestHarnessVersion(definition: HarnessDefinition): Promise<string | null>;
+export declare function $resolveLatestNpmPackageVersion(npmPackageName: string): Promise<string | null>;

package/esm/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the root directory under which npm installs global packages.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs npm
+ *
+ * @returns The global npm prefix or `null` when npm could not be asked for it
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveNpmGlobalPrefixPath(): Promise<string | null>;

package/esm/src/cli/cli-commands/common/npm/buildNpmPackageInstallCommand.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Place where an npm package should be installed or updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NpmPackageInstallationLocation = 'local-dependency' | 'local-development-dependency' | 'global';
+/**
+ * Builds an npm command which installs or updates a package in the requested existing location.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function buildNpmPackageInstallCommand(npmPackageName: string, installationLocation: NpmPackageInstallationLocation): string;

package/esm/src/cli/cli-commands/common/npm/extractNpmPackageVersionFromOutput.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extracts an npm package version from raw command output.
+ *
+ * Both npm and CLI commands may emit unrelated warnings before the version. CLI commands use the first matching token;
+ * npm registry commands can opt into the last matching token because npm warnings commonly precede their output.
+ *
+ * @returns The parsed version or `null` when the output contains no version
+ * @private internal utility of `promptbookCli`
+ */
+export declare function extractNpmPackageVersionFromOutput(output: string, { isLastMatchPreferred }?: {
+    readonly isLastMatchPreferred?: boolean;
+}): string | null;

package/esm/src/cli/cli-commands/common/npm/isNpmPackageVersionOutdated.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compares an installed npm package version with the newest published version.
+ *
+ * Release and prerelease identifiers follow semantic-version precedence while build metadata is ignored. Harnesses can
+ * preserve their historical behavior by setting `isPrereleaseIgnored`, because some harness commands report a build
+ * suffix which does not correspond to npm release precedence.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function isNpmPackageVersionOutdated(installedVersion: string, latestVersion: string, { isPrereleaseIgnored }?: {
+    readonly isPrereleaseIgnored?: boolean;
+}): boolean;

package/esm/src/cli/cli-commands/common/projectInitialization.d.ts

@@ -50,6 +50,12 @@ export declare function ensureProjectEnvFile<TEnvVariable extends ProjectEnvVari
  * @private internal utility of Promptbook CLI project initialization
  */
 export declare function ensureProjectGitignoreFile({ projectPath, blockHeader, rules, }: EnsureProjectGitignoreFileOptions): Promise<ProjectInitializationStatus>;
+/**
+ * Lists the ignore rules which are not yet present in a project's `.gitignore` file.
+ *
+ * @private internal utility of Promptbook CLI project initialization
+ */
+export declare function getMissingProjectGitignoreRules(projectPath: string, rules: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
 /**
  * Reads one text file when it exists, otherwise returns `undefined`.
  *

package/esm/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -1,5 +1,6 @@
 import { Command as Program } from 'commander';
 import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+import type { GitChangesMode } from '../coder/GitChangesMode';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
@@ -7,7 +8,7 @@ export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini", "qwen-code"];
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
@@ -25,7 +26,7 @@ export type PromptRunnerCliOptions = {
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly commit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -48,7 +49,7 @@ export type NormalizedPromptRunnerCliOptions = {
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
     readonly noCommit: boolean;
-    readonly ignoreGitChanges: boolean;
+    readonly gitChanges: GitChangesMode;
     readonly allowCredits: boolean;
     readonly normalizeLineEndings: boolean;
     readonly autoPush: boolean;
@@ -71,13 +72,25 @@ export declare const PROMPT_RUNNER_DESCRIPTION: string;
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = "Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)";
+export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION: string;
+/**
+ * Runner harness names listed as alternatives of the `--harness` option in error messages.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_HARNESS_OPTION_HINT: string;
 /**
  * Commander description for the `--model` option.
  *
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Commander description for the `--git-changes` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const GIT_CHANGES_OPTION_DESCRIPTION: string;
 /**
  * Registers runner selection flags on a command.
  *

package/esm/src/cli/cli-commands/common/promptbook-cli/$checkPromptbookCliInstallations.d.ts

@@ -0,0 +1,9 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Checks every local and global Promptbook CLI installation against the newest npm version.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads installed packages and queries npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $checkPromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallationStatus>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$ensurePromptbookCliInstallations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks local and global Promptbook CLI installations before an interactive coder run and offers to update them.
+ *
+ * Once an update succeeds, the caller must stop the current run and let the user start a fresh process. A local npm
+ * update can modify `package.json` and a lockfile, which would make the coder's clean-working-tree preflight fail;
+ * the current Node.js process has also already loaded the old CLI implementation.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests, queries npm,
+ * asks the user, and may install npm packages
+ *
+ * @returns `true` when at least one installation was updated and the current coder run should stop
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $ensurePromptbookCliInstallations(): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$resolvePromptbookCliInstallations.d.ts

@@ -0,0 +1,12 @@
+import { type PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Finds every directly declared local or directly installed global Promptbook CLI package which can be updated.
+ *
+ * Transitive packages are deliberately ignored because this command must update the dependency chosen by the current
+ * project or global npm installation, not mutate a dependency owned by another package.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads package manifests and runs npm
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolvePromptbookCliInstallations(): Promise<ReadonlyArray<PromptbookCliInstallation>>;

package/esm/src/cli/cli-commands/common/promptbook-cli/$updatePromptbookCliInstallation.d.ts

@@ -0,0 +1,10 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Updates one Promptbook CLI package in its existing local or global location.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs an npm package
+ *
+ * @returns `true` when the package update succeeds, `false` when it fails
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $updatePromptbookCliInstallation(status: PromptbookCliInstallationStatus): Promise<boolean>;

package/esm/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallation.d.ts

@@ -0,0 +1,66 @@
+import type { NpmPackageInstallationLocation } from '../npm/buildNpmPackageInstallCommand';
+/**
+ * Npm packages which directly provide the `ptbk` executable.
+ *
+ * `ptbk` is the preferred package and forwards to `@promptbook/cli`; the latter can also be installed directly.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPTBOOK_CLI_NPM_PACKAGE_NAMES: readonly ["ptbk", "@promptbook/cli"];
+/**
+ * Npm package which directly provides the `ptbk` executable.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliNpmPackageName = (typeof PROMPTBOOK_CLI_NPM_PACKAGE_NAMES)[number];
+/**
+ * Place where one Promptbook CLI package is installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationLocation = NpmPackageInstallationLocation;
+/**
+ * Fields shared by local and global Promptbook CLI installations.
+ *
+ * @private internal utility of `PromptbookCliInstallation`
+ */
+type PromptbookCliInstallationBase = {
+    /**
+     * Npm package that provides the CLI.
+     */
+    readonly npmPackageName: PromptbookCliNpmPackageName;
+    /**
+     * Version from the installed package's `package.json`.
+     */
+    readonly installedVersion: string;
+};
+/**
+ * One directly declared local Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type LocalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    /**
+     * Local manifest section containing the package.
+     */
+    readonly installationLocation: Exclude<PromptbookCliInstallationLocation, 'global'>;
+    /**
+     * Project directory containing the `package.json` which declares the package.
+     */
+    readonly projectPath: string;
+};
+/**
+ * One directly installed global Promptbook CLI package.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type GlobalPromptbookCliInstallation = PromptbookCliInstallationBase & {
+    readonly installationLocation: 'global';
+};
+/**
+ * One local or global Promptbook CLI package that can be updated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallation = LocalPromptbookCliInstallation | GlobalPromptbookCliInstallation;
+export {};

package/esm/src/cli/cli-commands/common/promptbook-cli/PromptbookCliInstallationStatus.d.ts

@@ -0,0 +1,26 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Result of comparing one installed Promptbook CLI package with the newest published version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationState = 'up-to-date' | 'outdated' | 'unknown';
+/**
+ * Version status of one Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptbookCliInstallationStatus = {
+    /**
+     * Installed CLI package being checked.
+     */
+    readonly installation: PromptbookCliInstallation;
+    /**
+     * Result of comparing the installed version with the newest published version.
+     */
+    readonly installationState: PromptbookCliInstallationState;
+    /**
+     * Newest published package version, or `null` when npm could not be reached.
+     */
+    readonly latestVersion: string | null;
+};

package/esm/src/cli/cli-commands/common/promptbook-cli/buildPromptbookCliInstallCommand.d.ts

@@ -0,0 +1,7 @@
+import type { PromptbookCliInstallation } from './PromptbookCliInstallation';
+/**
+ * Builds the npm command that updates one existing Promptbook CLI installation.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function buildPromptbookCliInstallCommand(installation: PromptbookCliInstallation): string;

package/esm/src/cli/cli-commands/common/promptbook-cli/formatPromptbookCliInstallationWarning.d.ts

@@ -0,0 +1,7 @@
+import type { PromptbookCliInstallationStatus } from './PromptbookCliInstallationStatus';
+/**
+ * Formats the warning shown when one or more Promptbook CLI installations are outdated.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatPromptbookCliInstallationWarning(statuses: ReadonlyArray<PromptbookCliInstallationStatus>): string;

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -84,8 +84,23 @@ export declare class AgentCollectionInSupabase {
     private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     getAgentPermanentId(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_agent_permanent_id>;
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private findAgentPermanentId;
     /**
      * Retrieves the source code of an agent by its name or permanent ID.
      */

package/esm/src/commitments/{COMPONENT/COMPONENT.d.ts → META_FULLNAME/META_FULLNAME.d.ts}

@@ -1,16 +1,19 @@
 import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
- * COMPONENT commitment definition
+ * META FULLNAME commitment definition
  *
- * The COMPONENT commitment defines a UI component that the agent can render in the chat.
+ * The `META FULLNAME` commitment sets the full display name of the agent, which can differ
+ * from the agent name on the first line of the agent source, for example when the agent
+ * should be presented with academic titles.
+ * This commitment is metadata-only and does not modify model requirements.
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class ComponentCommitmentDefinition extends BaseCommitmentDefinition<'COMPONENT'> {
+export declare class MetaFullnameCommitmentDefinition extends BaseCommitmentDefinition<'META FULLNAME'> {
     constructor();
     /**
-     * Short one-line description of COMPONENT.
+     * Short one-line description of META FULLNAME.
      */
     get description(): string;
     /**
@@ -18,7 +21,7 @@ export declare class ComponentCommitmentDefinition extends BaseCommitmentDefinit
      */
     get icon(): string;
     /**
-     * Markdown documentation for COMPONENT commitment.
+     * Markdown documentation for META FULLNAME commitment.
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;

package/esm/src/commitments/META_ID/META_ID.d.ts

@@ -0,0 +1,32 @@
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * META ID commitment definition
+ *
+ * The `META ID` commitment carries the permanent id of the agent when an agent source is moved
+ * between systems. It is a low-level commitment which is normally written and stripped by the
+ * persistence layer instead of being written by hand.
+ * This commitment is metadata-only and does not modify model requirements.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class MetaIdCommitmentDefinition extends BaseCommitmentDefinition<'META ID'> {
+    constructor();
+    /**
+     * Short one-line description of META ID.
+     */
+    get description(): string;
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string;
+    /**
+     * `META ID` is written by the persistence layer, not by agent authors.
+     */
+    get isLowLevel(): boolean;
+    /**
+     * Markdown documentation for META ID commitment.
+     */
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+}

package/esm/src/commitments/WRITING_RULES/WRITING_RULES.d.ts

@@ -3,23 +3,30 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * `WRITING RULES` commitment definition.
  *
- * It adds constraints that apply strictly to writing style and presentation
- * rather than task-solving behavior.
+ * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+ * and presentation rather than task-solving behavior.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * WRITING RULES Keep every response under 120 words
+ * WRITING RULE Always end the message with an emoji
+ * ```
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
-    constructor();
+export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES' | 'WRITING RULE'> {
+    constructor(type?: 'WRITING RULES' | 'WRITING RULE');
     /**
-     * Short one-line description of `WRITING RULES`.
+     * Short one-line description of `WRITING RULES`/`WRITING RULE`.
      */
     get description(): string;
     /**
-     * Icon for `WRITING RULES`.
+     * Icon for `WRITING RULES`/`WRITING RULE`.
      */
     get icon(): string;
     /**
-     * Markdown documentation for `WRITING RULES`.
+     * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;