@timurproko/a1 0.1.8-dev.151 → 0.1.8-dev.182

package/README.md

@@ -23,20 +23,28 @@ npm install -g @timurproko/a1@0.1.8-dev.107
 ## Use
 
 ```sh
-a1                      # launch A1 (profile: ~/.a1/agent)
-a1 version              # show Current, Develop, and Release versions
-a1 update               # install the newest stable release
-a1 update:develop       # install the current development preview
-a1 update:107           # install numbered preview 107
-a1 update --models      # refresh A1's model catalogs
+a1                                      # launch A1 (profile: ~/.a1/agent)
+a1 --help                               # show all commands (short form: a1 -h)
+a1 --version                            # show the version (short form: a1 -v)
+a1 update                               # install the newest stable release
+a1 update --develop                     # install the current development preview
+a1 update --develop 107                 # install numbered preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact preview
+a1 update --models                      # refresh A1's model catalogs
 ```
 
+Stable builds print only their installed version. Development builds also show the
+current development and stable channel versions.
+
 Development previews add the Pi comparison profile; release builds do not carry it.
 
 ```sh
-a1 pi           # vanilla Pi oracle: ~/.pi/agent
+a1 pi                                   # vanilla Pi oracle: ~/.pi/agent
 ```
 
+Unsupported commands exit quietly without launching anything. The removed
+`update:<preview>` forms are not aliases; use `update --develop`.
+
 ## Extensions
 
 Pi extension packages install into A1's own profile (`~/.a1/agent`), so bare `a1`
@@ -49,8 +57,12 @@ a1 pi remove npm:pi-mcp-adapter    # remove it (alias: a1 pi uninstall)
 a1 pi list                         # list installed packages
 a1 pi update --extensions          # update every installed package
 a1 pi update npm:pi-mcp-adapter    # update one
+a1 pi update --models              # refresh A1's model catalogs
 ```
 
+A1 pins the Pi runtime carried by each release, so Pi self-update forms are refused.
+Update A1 itself with `a1 update` or `a1 update --develop`.
+
 A running session picks up a newly installed package after a restart.
 Configuration is isolated the same way: bare `a1` reads `~/.a1/agent` (or the
 project), never `~/.pi/agent`. Configure MCP with `/mcp setup` inside bare `a1`.
@@ -66,6 +78,38 @@ npm run test:fast       # typecheck + fast suite (alias: npm test)
 npm run test:full       # complete non-physical suite
 ```
 
+Create every task worktree at `{working-dir}/.worktrees/<task-id>`, where
+`{working-dir}` is the session's initial working directory. For working directory
+`D:/Git/a1`, use `D:/Git/a1/.worktrees/<task-id>`—never a sibling such as
+`D:/Git/a1-<task-id>`. The primary worktree remains on `develop` for integration only.
+
+## Pull request integration
+
+Pull requests whose complete diff is only under `openspec/**`, under `docs/**`,
+exactly the root `README.md`, or a combination of those paths are automatically
+squash-merged after `Development validation required` succeeds. The automation
+reads the complete GitHub changed-file list, including both sides of renames, and
+runs only for trusted branches in this repository.
+
+Any other path makes the pull request code/operational. That includes source, tests,
+scripts, workflows, configuration, generated baselines, arbitrary root Markdown,
+and a mixed documentation-plus-code change. Those pull requests remain open after
+CI for local maintainer validation and explicit manual merge; automation disables
+auto-merge if it was armed. Documentation remains exempt from product builds and
+tests, but docs-sensitive generated governance and strict OpenSpec consistency are
+checked before integration.
+
+After any same-repository pull request into `develop` merges, trusted automation
+reconciles its remote topic branch. Human merges use the close-event workflow;
+documentation merges authored by `GITHUB_TOKEN` use a synchronous fallback because
+GitHub suppresses recursive workflow events. Both delete only an unprotected live
+ref that still equals the pull request's exact merged head SHA. Fork, advanced,
+reserved, protected, malformed, and unmerged refs are preserved and reported.
+
+Specification approval and implementation remain separate pull requests. An
+implementation starts from updated `origin/develop` only after its specification
+has merged and implementation was explicitly requested.
+
 ## Release
 
 Two channels, both published by CI from the exact bytes it validated — never from
@@ -88,8 +132,8 @@ npm run develop             # request the preview publish run and wait for it
 Install:
 
 ```sh
-a1 update:107               # install preview 107
-a1 update:0.1.8-dev.107     # install that exact full preview version
+a1 update --develop 107                 # install preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact full preview version
 ```
 
 ### Stable

package/bin/cli.js

@@ -45,5 +45,6 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     return await runPackageCommand(request, { createPort: createPiPackagesPort });
   },
 }, {
+  stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),
 }, capabilities);

package/bin/ui.js

@@ -12,13 +12,28 @@ assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), m
 
 const { runSelectedInteractiveRuntime } = await import("../dist/features/launch/index.js");
 
+const launchArgs = process.argv.slice(2);
+let sessionPath;
+if (launchArgs.length > 0) {
+  if (launchArgs.length !== 2 || launchArgs[0] !== "--session" || launchArgs[1].trim().length === 0) {
+    throw new Error("Usage: a1 [--session <session-file>]");
+  }
+  sessionPath = launchArgs[1];
+}
+
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
   ownedUi: async (profileId, ownedSurfaces) => {
-    const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
+    const [{ createConsoleProjectTrustPrompt, runOwnedUi }, { composeOwnedUi }] = await Promise.all([
       import("../dist/features/owned-ui/index.js"),
       import("../dist/composition/index.js"),
     ]);
-    const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
+    const { application, settings } = await composeOwnedUi({
+      cwd: process.cwd(),
+      profileId,
+      ownedSurfaces,
+      projectTrustPrompt: createConsoleProjectTrustPrompt(),
+      ...(sessionPath === undefined ? {} : { sessionPath }),
+    });
     return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
   },
 }).then(

package/dist/cli/dispatch.d.ts

@@ -9,11 +9,17 @@ export interface CliHandlers {
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
+    readonly stdout: (message: string) => void;
     readonly stderr: (message: string) => void;
 }
 export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function cliHelp(capabilities: CliCapabilities): string;
 export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
+    readonly kind: "noop";
+} | {
+    readonly kind: "help";
+} | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
 } | {

package/dist/cli/dispatch.js

@@ -4,21 +4,60 @@ export function cliUsage(capabilities) {
     return PRODUCT_TEXT.usage([
         "",
         ...(capabilities.developmentComparison ? ["pi"] : []),
-        "version",
-        "update [self|--models]",
-        "update:develop",
-        "update:<number>",
+        "--help",
+        "-h",
+        "--version",
+        "-v",
+        "update",
+        "update --develop [preview-or-version]",
+        "update --models",
         "pi install <source>",
         "pi remove <source>",
+        "pi uninstall <source>",
         "pi list",
-        "pi update [--extensions|<source>]",
+        "pi update --extensions",
+        "pi update --models",
+        "pi update <source>",
     ]);
 }
+export function cliHelp(capabilities) {
+    const command = PRODUCT_TEXT.commandName;
+    return [
+        "Common:",
+        `  ${command}`,
+        ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
+        `  ${command} --help`,
+        `  ${command} -h`,
+        `  ${command} --version`,
+        `  ${command} -v`,
+        "",
+        "Update:",
+        `  ${command} update`,
+        `  ${command} update --develop [preview-or-version]`,
+        `  ${command} update --models`,
+        "",
+        "Pi-compatible packages:",
+        `  ${command} pi install <source>`,
+        `  ${command} pi remove <source>`,
+        `  ${command} pi uninstall <source>`,
+        `  ${command} pi list`,
+        `  ${command} pi update --extensions`,
+        `  ${command} pi update --models`,
+        `  ${command} pi update <source>`,
+        "",
+    ].join("\n");
+}
 const PROFILE_WORDS = new Set(["pi"]);
 export async function dispatchCli(arguments_, handlers, output, capabilities) {
     const command = parseCliCommand(arguments_, capabilities);
+    if (command.kind === "noop")
+        return 0;
+    if (command.kind === "help") {
+        output.stdout(cliHelp(capabilities));
+        return 0;
+    }
     if (command.kind === "error") {
-        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
+        output.stderr(`${command.message}\n`);
         return 2;
     }
     if (command.kind === "launch")
@@ -33,76 +72,63 @@ export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
         return { kind: "launch", profileId: "a1" };
     const [command, ...rest] = arguments_;
+    if (command === "--help" || command === "-h")
+        return withoutArguments(rest, { kind: "help" });
+    if (command === "--version" || command === "-v")
+        return withoutArguments(rest, { kind: "version" });
     if (command === "pi") {
         if (rest.length > 0)
             return parsePiPackageCommand(rest);
-        if (capabilities.developmentComparison)
-            return { kind: "launch", profileId: "pi" };
+        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
     }
-    if (command === "version")
-        return withoutArguments(rest, { kind: "version" });
-    if (command !== undefined && command.startsWith("update:"))
-        return parseColonUpdate(command.slice("update:".length), rest);
     if (command === "update")
         return parseUpdate(rest);
-    if (command === "install" || command === "remove" || command === "uninstall" || command === "list") {
-        return packageNamespaceRejection(command, rest.join(" ") || undefined);
-    }
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
-    if (command === "agent")
-        return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
+    if (command?.startsWith("update:"))
+        return { kind: "noop" };
+    // Unsupported and reserved command spaces are deliberately quiet. Help is
+    // explicit, and a typo must never start an interactive or maintenance path.
+    return { kind: "noop" };
 }
 /**
- * What follows the colon says which development build to move to. `develop`
- * selects the channel head; a positive decimal or a full numbered preview names
- * one immutable publication.
- */
-function parseColonUpdate(suffix, rest) {
-    if (rest.length > 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
-    if (suffix === "next") {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`renamed its development channel; run ${PRODUCT_TEXT.commandName} update:develop.`) };
-    }
-    if (suffix === "develop")
-        return { kind: "update", channel: "next" };
-    if (suffix.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:develop.`) };
-    if (!/^[1-9]\d*$/.test(suffix) && !/^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(suffix)) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable numbered preview: ${suffix}`) };
-    }
-    return { kind: "update", channel: "next", target: suffix };
-}
-/**
- * Top-level `update` owns A1 itself and A1's model catalogs. Extension package
- * maintenance lives under the `pi` compatibility namespace, while updating the
- * pinned Pi runtime remains impossible.
+ * Stable update is the empty form. `--develop` selects the moving development
+ * head or one immutable numbered preview, while model refresh remains a separate
+ * operation that cannot be combined with either update channel.
  */
 function parseUpdate(rest) {
     if (rest.length === 0)
         return { kind: "update", channel: "stable" };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
-    const [target] = rest;
-    if (target === "self")
-        return { kind: "update", channel: "stable" };
-    if (target === "pi") {
-        return {
-            kind: "error",
-            message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
-        };
-    }
-    if (target === "next" || target === "develop" || target === "stable") {
-        const form = target === "stable" ? `${PRODUCT_TEXT.commandName} update` : `${PRODUCT_TEXT.commandName} update:develop`;
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
+    const [selector, ...values] = rest;
+    // Removed compatibility notation is unsupported rather than deprecated.
+    if (selector === "self")
+        return { kind: "noop" };
+    if (selector === "--develop") {
+        if (values.length === 0)
+            return { kind: "update", channel: "next" };
+        if (values.length > 1)
+            return updateGrammarError("--develop accepts at most one preview number or version.");
+        const [target] = values;
+        if (target === undefined || !isDevelopmentTarget(target)) {
+            return updateGrammarError(`--develop received an unusable preview: ${target ?? ""}`);
+        }
+        return { kind: "update", channel: "next", target };
     }
-    if (target === "--models")
+    if (selector === "--models") {
+        if (values.length > 0)
+            return updateGrammarError("--models cannot be combined with another update selector.");
         return { kind: "packages", request: { verb: "refresh-models", source: null } };
-    if (target === "--extensions" || (target !== undefined && !target.startsWith("-"))) {
-        return packageNamespaceRejection("update", target === "--extensions" ? "--extensions" : target);
     }
-    return unknownOption(target ?? "", "update");
+    if (selector === "pi")
+        return pinnedPiUpdateError();
+    if (selector !== undefined && selector.startsWith("-"))
+        return unknownOption(selector, "update");
+    // Positional update targets are reserved for a future A1-native plugin model.
+    return { kind: "noop" };
+}
+function isDevelopmentTarget(target) {
+    return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
+}
+function updateGrammarError(detail) {
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
 }
 function parsePiPackageCommand(arguments_) {
     const [verb, ...rest] = arguments_;
@@ -113,30 +139,40 @@ function parsePiPackageCommand(arguments_) {
         return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
     if (verb === "update")
         return parsePiPackageUpdate(rest);
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown pi package command: ${verb ?? ""}`) };
+    return { kind: "noop" };
 }
 function parsePiPackageUpdate(rest) {
-    if (rest.length === 0) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`pi update needs --extensions or a package source.`) };
-    }
+    if (rest.length === 0)
+        return pinnedPiUpdateError();
     if (rest.length > 1)
         return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
     const [target] = rest;
     if (target === "--extensions")
         return { kind: "packages", request: { verb: "update", source: null } };
-    if (target === "--models") {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`refreshes its model catalogs at the top level; run ${PRODUCT_TEXT.commandName} update --models.`) };
-    }
+    if (target === "--models")
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    if (target === "--self" || target === "--all" || target === "self" || target === "pi")
+        return pinnedPiUpdateError();
     if (target === undefined || target.startsWith("-"))
         return unknownOption(target ?? "", "pi update");
-    if (PROFILE_WORDS.has(target))
-        return profileRejection("update");
     return { kind: "packages", request: { verb: "update", source: target } };
 }
+function pinnedPiUpdateError() {
+    return {
+        kind: "error",
+        message: [
+            PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
+            "Use:",
+            `  ${PRODUCT_TEXT.commandName} update                    Update A1`,
+            `  ${PRODUCT_TEXT.commandName} pi update --extensions    Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} pi update --models        Refresh model catalogs`,
+        ].join("\n"),
+    };
+}
 function parseSourceCommand(verb, rest) {
     const flag = rest.find(argument => argument.startsWith("-"));
     if (flag !== undefined)
-        return unknownOption(flag, verb);
+        return unknownOption(flag, `pi ${verb}`);
     if (rest.length === 0)
         return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
     if (rest.length > 1)
@@ -151,18 +187,8 @@ function parseSourceCommand(verb, rest) {
 function withoutArguments(rest, command) {
     if (rest.length === 0)
         return command;
-    const [argument] = rest;
-    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
-        return profileRejection("list");
     return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
 }
-function packageNamespaceRejection(verb, target) {
-    const suffix = target === undefined ? "" : ` ${target}`;
-    return {
-        kind: "error",
-        message: PRODUCT_TEXT.diagnostic(`manages extension packages under its pi namespace; run ${PRODUCT_TEXT.commandName} pi ${verb}${suffix}.`),
-    };
-}
 function profileRejection(verb) {
     return {
         kind: "error",

package/dist/cli/version-stats.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import crossSpawn from "cross-spawn";
-import { valid as validSemver } from "semver";
+import { prerelease, valid as validSemver } from "semver";
 import { PRODUCT_TEXT } from "../product-identity.js";
 const defaultOutput = {
     stdout(message) { process.stdout.write(message); },
@@ -20,6 +20,12 @@ export async function runVersionStats(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
         return 1;
     }
+    // Match Pi's release behavior: stable builds print only their installed version.
+    // Development builds retain channel visibility for preview comparison and updates.
+    if (prerelease(installed) === null) {
+        output.stdout(`${installed}\n`);
+        return 0;
+    }
     const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
     output.stdout(`Current: ${installed}\nDevelop: ${remote.develop ?? "unavailable"}\nRelease: ${remote.release ?? "unavailable"}\n`);
     if (remote.error)

package/dist/composition/owned-ui.d.ts

@@ -1,10 +1,12 @@
-import { type PiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/index.js";
 import { OwnedUiSettingsSession } from "../ui/settings/index.js";
 import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
 export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /** Exact persisted session selected by the narrow `--session` launch form. */
+    readonly sessionPath?: string;
     /**
      * A1 profile whose settings this session reads and writes. Omitted keeps the
      * session settings-free, which is what the pinned comparison paths use.
@@ -15,6 +17,7 @@ export interface OwnedUiCompositionOptions {
      * use the same composition with those surfaces withheld.
      */
     readonly ownedSurfaces?: "on" | "off";
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
 }
 export interface OwnedUiComposition {
     readonly application: OwnedUiApplicationPort;

package/dist/composition/owned-ui.js

@@ -1,6 +1,6 @@
 import { resolveProductPaths } from "../foundation/lifecycle/index.js";
 import { applyConfiguredPiTheme, getAvailablePiThemes } from "../integrations/pi/components/index.js";
-import { createPiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { createPiEngineAdapter, } from "../integrations/pi/engine/index.js";
 import { OwnedUiSessionShell } from "../integrations/pi/session-ui/index.js";
 import { OwnedUiSettingsSession, OwnedUiSettingsStore } from "../ui/settings/index.js";
 import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/index.js";
@@ -12,16 +12,19 @@ export async function composeOwnedUi(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const adapter = options.createPiAdapter
         ? await options.createPiAdapter()
-        : await createPiEngineAdapter({ cwd, availableThemes: () => getAvailablePiThemes().map(theme => theme.name) });
+        : await createPiEngineAdapter({
+            cwd,
+            availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
+            settingsProductMode: options.ownedSurfaces === "off" ? "comparison" : "bare",
+            ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+        });
     const ownedSurfaces = options.ownedSurfaces !== "off";
     const settings = options.profileId === undefined
         ? null
         : new OwnedUiSettingsSession({
             store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
             agentProvider: () => adapter.settingsPort(),
-            ...(ownedSurfaces ? {
-                hiddenAgentSettingIds: ["tuiMode", "theme", "fullscreenScrollbar", "quietStartup"],
-            } : {}),
         });
     // Bare A1 intentionally ships one visual target while its UI is being completed:
     // dark, regardless of terminal detection or a previously stored Pi theme. The

package/dist/contracts/agent-engine/capability-ports.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJsonValue, AgentModelDescriptor, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
+import type { AgentJsonValue, AgentModelDescriptor, AgentSettingChangeOutcome, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
 export interface AgentModelPort {
     readonly capabilities: {
         readonly selection: boolean;
@@ -26,7 +26,7 @@ export interface AgentSettingsPort {
     };
     listSettings(): Promise<readonly AgentSettingDescriptor[]>;
     readSetting(key: string): Promise<AgentJsonValue | undefined>;
-    writeSetting?(key: string, value: AgentJsonValue): Promise<void>;
+    writeSetting?(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
     flush?(): Promise<void>;
 }
 export interface AgentResourcesPort {

package/dist/contracts/agent-engine/domain-validation.js

@@ -52,10 +52,28 @@ export function assertAgentUsage(value) { for (const amount of [value.inputToken
     nonNegative(amount, "usage token count"); if (value.cost !== null && (!(typeof value.cost === "number") || !Number.isFinite(value.cost) || value.cost < 0))
     throw new TypeError("usage cost is invalid"); }
 export function assertAgentModelDescriptor(value) { id(value.providerId, "model provider id"); id(value.modelId, "model id"); text(value.displayName, "model display name"); nonNegative(value.contextWindow, "model context window"); unique(value.thinkingLevels, undefined, "model thinking levels"); }
-export function assertAgentSettingDescriptor(value) { id(value.key, "setting key"); if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType) || typeof value.writable !== "boolean")
-    throw new TypeError("setting descriptor is invalid"); if (value.choices)
-    for (const choice of value.choices)
-        json(choice, "setting choice"); }
+export function assertAgentSettingDescriptor(value) {
+    id(value.key, "setting key");
+    if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType)
+        || typeof value.writable !== "boolean"
+        || !["live", "next-session", "next-start", "current-exit"].includes(value.application)
+        || !["agent", "shell", "terminal", "startup", "shutdown", "installation"].includes(value.owner)
+        || typeof value.available !== "boolean"
+        || !(value.limitationReason === null || typeof value.limitationReason === "string")) {
+        throw new TypeError("setting descriptor is invalid");
+    }
+    json(value.storedValue, "stored setting value");
+    json(value.effectiveValue, "effective setting value");
+    if ((value.available && value.limitationReason !== null)
+        || (!value.available && (value.limitationReason === null || value.limitationReason.length === 0))) {
+        throw new TypeError("setting descriptor availability is contradictory");
+    }
+    if (value.writable && !value.available)
+        throw new TypeError("unavailable setting cannot be writable");
+    if (value.choices)
+        for (const choice of value.choices)
+            json(choice, "setting choice");
+}
 export function assertAgentResourceDescriptor(value) { id(value.id, "resource id"); if (!["command", "prompt", "skill", "extension", "other"].includes(value.kind))
     throw new TypeError("resource kind is invalid"); text(value.label, "resource label"); json(value.metadata, "resource metadata"); }
 export function assertAgentThemeDescriptor(value) { id(value.id, "theme id"); text(value.label, "theme label"); if (!value.tokens || typeof value.tokens !== "object" || Object.values(value.tokens).some(token => typeof token !== "string"))

package/dist/contracts/agent-engine/domain.d.ts

@@ -48,10 +48,27 @@ export interface AgentModelDescriptor {
     readonly contextWindow: number;
     readonly thinkingLevels: readonly string[];
 }
+export type AgentSettingApplicationBoundary = "live" | "next-session" | "next-start" | "current-exit";
+export type AgentSettingOwner = "agent" | "shell" | "terminal" | "startup" | "shutdown" | "installation";
+export interface AgentSettingChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly application: AgentSettingApplicationBoundary;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
+    readonly failure: string | null;
+    readonly limitationReason: string | null;
+}
 export interface AgentSettingDescriptor {
     readonly key: string;
     readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+    /** A setting is writable only when its declared owner/effect is available. */
     readonly writable: boolean;
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly available: boolean;
+    readonly limitationReason: string | null;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
     readonly choices?: readonly AgentJsonValue[];
     /** Label the engine shows for this setting, when it has one. */
     readonly label?: string;

package/dist/contracts/owned-ui/model.d.ts

@@ -91,6 +91,12 @@ export interface OwnedUiOverlay {
     readonly modal: boolean;
     readonly payload: unknown;
 }
+export interface OwnedUiTranscriptImageReference {
+    readonly assetId: OwnedUiEntityId;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly source: "user" | "tool-result";
+}
 export interface OwnedUiTranscriptBlock {
     readonly id: OwnedUiEntityId;
     readonly kind: OwnedUiTranscriptBlockKind;
@@ -99,6 +105,8 @@ export interface OwnedUiTranscriptBlock {
     readonly title: string | null;
     readonly text: string;
     readonly payload: unknown;
+    /** Bounded opaque references; image bytes remain in the session-scoped engine asset store. */
+    readonly imageReferences?: readonly OwnedUiTranscriptImageReference[];
 }
 export type OwnedUiSlotId = "theme" | "transcript-block" | "tool-card" | "editor" | "status" | "command" | "selector" | "dialog" | "overlay" | "layout";
 export interface OwnedUiCustomization {

package/dist/contracts/owned-ui/validation.js

@@ -14,6 +14,7 @@ const MAX_QUEUE = 32;
 const MAX_BADGES = 32;
 const MAX_STATUS_DIAGNOSTICS = 32;
 const MAX_ACTIVE_COMMANDS = 64;
+const IMAGE_REFERENCE_SOURCES = new Set(["user", "tool-result"]);
 const BLOCK_KINDS = new Set([
     "user",
     "assistant",
@@ -225,6 +226,16 @@ export function assertOwnedUiTranscriptBlock(block) {
     assertOptionalText(block.title, "owned-UI transcript block title", MAX_LABEL_LENGTH);
     assertPossiblyEmptyText(block.text, "owned-UI transcript block text", MAX_TEXT_BYTES);
     assertJsonValue(block.payload, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    if (block.imageReferences !== undefined) {
+        assertCollection(block.imageReferences, "owned-UI transcript image references", 16);
+        for (const reference of block.imageReferences) {
+            assertId(reference.assetId, "owned-UI transcript image asset id");
+            if (!/^image\/[a-z0-9.+-]+$/i.test(reference.mimeType))
+                throw new TypeError("owned-UI transcript image MIME type is invalid");
+            assertIntegerInRange(reference.byteLength, 1, 20 * 1024 * 1024, "owned-UI transcript image byte length");
+            assertEnum(reference.source, IMAGE_REFERENCE_SOURCES, "owned-UI transcript image source");
+        }
+    }
 }
 export function assertOwnedUiEditorState(editor) {
     assertPossiblyEmptyText(editor.text, "owned-UI editor text", MAX_TEXT_BYTES);

package/dist/features/owned-ui/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./project-trust-prompt.js";
 export * from "./settings-app.js";

package/dist/features/owned-ui/index.js

@@ -1,4 +1,5 @@
 export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
+export * from "./project-trust-prompt.js";
 export * from "./settings-app.js";