@synopackageland/cli 0.40.0 → 0.41.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+## 0.41.1 (2026-10-29)
+
+- `ui.banner: shown | hidden` lets an App choose whether DSM draws its banner
+  (App name, account menu) above the App's standalone page. `shown`, the
+  default, keeps today's page. `hidden` drops it for this App only, as DSM's
+  global "Hide banner" setting does, without touching that setting or a
+  desktop window's title bar. Meant for Apps whose own frame names the App and
+  shows the account; the SDK's `AppShell` then shows the account and a Sign
+  out button. The host adapter's new `ctx.host.signOut()` signs out of DSM the
+  way the banner's menu does. `STANDALONE_UI_BANNER_INVALID` refuses other values.
+
+- Sync the bundled skill with SDK/App 0.38.0: 300-second requests, 302-second
+  browser waits and existing background admission, progress and status polling.
+  Preserve explicit budgets, original job IDs/keys and ctl's 62-second transport.
+- Select templates 0.35.1 with SDK/App 0.38.0 for new projects.
+
+## 0.41.0 (2026-10-29)
+
+- Add generic `ctl external --protocol <id> --host <profile> --input - --json`
+  for local MCP bridges. Apps opt in with `ctl.external` and a dedicated
+  administrator RPC entry. Each request checks the stored login, pinned host,
+  installed package and fresh description; calls also check the current catalog
+  revision and schema. The App verifies pins/revision at dispatch and creates
+  caller authority and MCP provenance. Ordinary ctl cannot invoke the external
+  entry. Lost mutation replies are never retried. See
+  [the external contract](docs/ctl-external.md) for App integration requirements.
+
 ## 0.40.0 (2026-10-29)
 
 - `daemon.backend: true` runs the App's own native backend

package/README.md

@@ -61,6 +61,10 @@ from `target/app` as the package account for each request (see `skills/reference
 Application Privileges admission, explicit method policies, gateway conflicts and
 the build-bound SDK checks.
 
+[External callers](docs/ctl-external.md) describes the local MCP bridge command,
+App-declared protocols and required trusted administrator entry. This opt-in
+contract does not add an MCP server or automatically wire an App's tool Engine.
+
 ## SDK and templates
 
 The CLI packages, deploys and checks. The app-side code is the SDK
@@ -78,7 +82,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.40.0 uses templates ~0.35.0, whose default SDK pin is 0.37.0. Compose import and SDK defaults
+CLI 0.41.1 uses templates ~0.35.1, whose default SDK pin is 0.38.0. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -89,7 +93,7 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.40.0 depends on `~0.35.0`: npm installation or
+`@synopackageland/templates`. CLI 0.41.1 depends on `~0.35.1`: npm installation or
 update can select the latest templates patch in the 0.35 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
@@ -328,6 +332,23 @@ a one-line reload notice. The wrapper sets the standalone
 page title, favicon and device-width viewport. It retains ExtJS; `pureEnv` is
 not appropriate, and alternate Portal ports are not needed (`allowAltPort` is omitted).
 
+`ui.banner: shown | hidden` chooses whether DSM draws its banner (the App's
+name and the account menu) above the App's standalone page. The default,
+`shown`, keeps DSM's behavior. `hidden` drops it for this App only, with the
+class DSM's global "Hide banner" setting uses, and leaves DSM's setting and a
+DSM desktop window's title bar alone. Hide it when the App's own frame already
+names the App and shows the account, for example a full-page web App built on
+the SDK's `AppShell`: the shell then shows the signed-in account and a Sign out
+button (`ctx.host.signOut()`, DSM's banner sign-out). Keep the banner when the
+App has no account area of its own.
+
+```yaml
+ui:
+  dir: ui/dist
+  launch: new-page
+  banner: hidden
+```
+
 A full page does not need Application Portal. Omit `portal` unless an alias is
 explicitly wanted; only that opt-in adds `defaultAlias`, login styling, Portal
 panels and capabilities. No Portal is a healthy default for inspect/info/doctor.

package/dist/cli.js

@@ -297,6 +297,10 @@ async function containerBuild(project, arches, options) {
 }
 /** Resolves after dispatch; commands may set process.exitCode. Rejections are failures. */
 export async function runCli(argv) {
+    if (argv[2] === 'ctl' && argv[3] === 'external') {
+        const { runCtl } = await import('./ctl/cli.js');
+        return runCtl(argv.slice(3));
+    }
     const { args, options } = nasFlags(argv, argv[2] !== "ctl");
     return withNasOptions(options, () => runCliWithin(args));
 }

package/dist/ctl/cli.d.ts

@@ -10,17 +10,6 @@ export interface CtlIO {
     requestFor?: (host: Host) => JsonRequest;
 }
 export declare function listView(host: string, apps: Descriptor[]): {
-    host: string;
-    package: {
-        id: string;
-        version: string;
-        displayName: string;
-    };
-    aliases: string[];
-    protocolVersion: 1;
-    developedBy: string;
-    provenance: string;
-    hash: string;
     commands: {
         parameters: string | Record<string, any>;
         examples: string[];
@@ -33,5 +22,19 @@ export declare function listView(host: string, apps: Descriptor[]): {
         flow: import("./descriptor.js").Flow;
         id: string;
     }[];
+    external?: Record<string, {
+        method: string;
+    }> | undefined;
+    host: string;
+    package: {
+        id: string;
+        version: string;
+        displayName: string;
+    };
+    aliases: string[];
+    protocolVersion: 1;
+    developedBy: string;
+    provenance: string;
+    hash: string;
 }[];
 export declare function runCtl(argv: string[], io?: CtlIO): Promise<void>;

package/dist/ctl/cli.js

@@ -10,6 +10,7 @@ import { selectHosts, selectApp, selectOperation, flagName, RESERVED_FLAGS } fro
 import { canonicalOrigin, CTL_TIMEOUT_MS, createRequest } from './transport.js';
 import { loginDsm, logoutDsm } from './dsm-auth.js';
 import { publicOperation } from './redaction.js';
+import { runExternal } from './external.js';
 const USAGE = 'synopkgland host add|list|show|login|logout|remove|revoke|default|trust; ctl list [--host a,b|--all-hosts] [--app pkg] [--refresh]; ctl <alias|package> <command...> [typed flags|--input file|-] [--dry-run] [--yes]; NAS HTTPS accepts any certificate by default; --strict-tls or --ca <file> opts into verification';
 async function prompt(message, secret = false) {
     if (!process.stdin.isTTY)
@@ -59,8 +60,10 @@ function example(host, app, op) {
         return `printf '%s' ${q(JSON.stringify(params))} | ${base} --input -` + (op.effect === 'read' ? '' : ' --yes');
     });
 }
-export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', examples: example(host, app, op) }; }) })); }
+export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, ...(app.payload.external ? { external: app.payload.external } : {}), commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', examples: example(host, app, op) }; }) })); }
 export async function runCtl(argv, io = {}) {
+    if (argv[0] === 'external')
+        return runExternal(argv.slice(1), io);
     try {
         const { args, options } = nasFlags(argv);
         return await withNasOptions({ ...options, warn: io.err ?? console.error }, () => runCtlWithin(args, io));

package/dist/ctl/descriptor.d.ts

@@ -66,6 +66,9 @@ export interface ApiPayload {
     };
     commands: Record<string, Operation>;
     bindings: Record<string, Binding>;
+    external?: Record<string, {
+        method: string;
+    }>;
 }
 export interface Descriptor {
     format: 'synopkgland.api';

package/dist/ctl/descriptor.js

@@ -27,6 +27,13 @@ export function validateDescriptor(value, id, version) {
         return fail('Invalid command allowlist.');
     if (!p.bindings || typeof p.bindings !== 'object')
         return fail('Missing internal method bindings.');
+    const externalMethods = new Set();
+    for (const entry of Object.values(p.external ?? {})) {
+        const binding = p.bindings[entry.method];
+        if (!binding || binding.permission !== 'administrators' || binding.effect !== 'destructive' || entry.method.startsWith('identity.') || entry.method === DESCRIPTION_METHOD)
+            return fail('External entries require dedicated administrator bindings.');
+        externalMethods.add(entry.method);
+    }
     const paths = new Set();
     for (const [method, raw] of Object.entries(p.commands)) {
         const op = raw;
@@ -38,6 +45,8 @@ export function validateDescriptor(value, id, version) {
         catch {
             return fail('Invalid command flow or method bindings.');
         }
+        if (externalMethods.has(method) || flowMethods(op.flow).some(name => externalMethods.has(name)))
+            return fail('External entries cannot be ordinary commands or flow helpers.');
         const path = op.cli.join(' ');
         if (paths.has(path))
             return fail('Duplicate CLI command path.');

package/dist/ctl/external.d.ts

@@ -0,0 +1,27 @@
+import { CtlStore, type Host } from './store.js';
+import { type JsonRequest } from './transport.js';
+import type { CtlIO } from './cli.js';
+type Describe = {
+    protocol: string;
+    action: 'describe';
+};
+type Call = {
+    protocol: string;
+    action: 'call';
+    revision: string;
+    method: string;
+    arguments: Record<string, unknown>;
+};
+export type ExternalRequest = Describe | Call;
+export declare function parseExternalRequest(raw: string, protocol: string): ExternalRequest;
+/** A separate entry, never an ordinary ctl flow with relabeled provenance. */
+export declare class ExternalClient {
+    private readonly store;
+    private readonly host;
+    private readonly request;
+    private readonly deadline;
+    constructor(store: CtlStore, host: Host, request?: JsonRequest);
+    execute(protocol: string, input: ExternalRequest): Promise<unknown>;
+}
+export declare function runExternal(argv: string[], io?: CtlIO): Promise<void>;
+export {};

package/dist/ctl/external.js

@@ -0,0 +1,195 @@
+import { CtlError, ctlError } from './errors.js';
+import { readBounded, strictJson } from './json.js';
+import { ajv, safeSchema, validateDescriptor } from './descriptor.js';
+import { CtlStore } from './store.js';
+import { CtlClient } from './service.js';
+import { canonicalOrigin, createRequest } from './transport.js';
+import { nasOptions } from '../nas/options.js';
+import { SensitiveOutput } from './redaction.js';
+const LIMIT = 1048576;
+const PROTOCOL = /^[a-z][a-z0-9-]{0,63}$/;
+const METHOD = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const AUTHORITY_KEYS = ['actor', 'via', 'allowMutation', 'allow_mutation', 'host'];
+const USAGE = 'synopkgland ctl external --protocol <declared-protocol> --host <profile> --input - --json';
+const HINT = 'Check local login, administrator access, App approval and tool revision. Query original state before repeating a mutation.';
+function fail(code, message, exit = 4) { throw new CtlError(code, message, HINT, exit); }
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function revision(value) { return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value); }
+export function parseExternalRequest(raw, protocol) {
+    try {
+        if (!PROTOCOL.test(protocol) || Buffer.byteLength(raw) > LIMIT)
+            throw Error();
+        const value = strictJson(raw);
+        if (!object(value) || value.protocol !== protocol)
+            throw Error();
+        const keys = value.action === 'describe' ? ['protocol', 'action'] : ['protocol', 'action', 'revision', 'method', 'arguments'];
+        if (Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value, key)))
+            throw Error();
+        if (value.action === 'describe')
+            return value;
+        if (value.action !== 'call' || !revision(value.revision) || typeof value.method !== 'string' || value.method.length > 128 || !METHOD.test(value.method) || !object(value.arguments) || AUTHORITY_KEYS.some(key => Object.hasOwn(value.arguments, key)))
+            throw Error();
+        return value;
+    }
+    catch {
+        return fail('CTL_EXTERNAL_INPUT', 'Invalid external request.', 3);
+    }
+}
+function validateCatalog(value) {
+    if (!object(value) || !revision(value.revision) || !Array.isArray(value.tools) || value.tools.length > 1024)
+        return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool catalog.', 5);
+    const methods = new Set(), names = new Set();
+    for (const tool of value.tools) {
+        if (!object(tool) || typeof tool.name !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(tool.name) ||
+            !object(tool._meta) || typeof tool._meta.method !== 'string' || tool._meta.method.length > 128 || !METHOD.test(tool._meta.method) ||
+            methods.has(tool._meta.method) || names.has(tool.name) || !object(tool.inputSchema) || !object(tool.outputSchema))
+            return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool metadata.', 5);
+        methods.add(tool._meta.method);
+        names.add(tool.name);
+        try {
+            for (const schema of [tool.inputSchema, tool.outputSchema]) {
+                safeSchema(schema);
+                ajv.compile(schema);
+            }
+        }
+        catch {
+            return fail('CTL_EXTERNAL_CATALOG', 'Invalid external tool schema.', 5);
+        }
+    }
+    return value;
+}
+/** A separate entry, never an ordinary ctl flow with relabeled provenance. */
+export class ExternalClient {
+    store;
+    host;
+    request;
+    deadline = performance.now() + 30000;
+    constructor(store, host, request) {
+        this.store = store;
+        this.host = host;
+        this.request = request ?? createRequest(host.origin, () => Math.max(0, this.deadline - performance.now()), undefined, { ...store.trust(host), expectedFingerprint: host.fingerprint });
+    }
+    async execute(protocol, input) {
+        input = parseExternalRequest(JSON.stringify(input), protocol);
+        // Ambient credentials and URL overrides are for ordinary automation only.
+        if (this.host.ephemeral || canonicalOrigin(this.host.origin, !!this.host.tunnel) !== this.host.origin ||
+            this.host.origin.startsWith('https:') && !/^[a-f0-9]{64}$/.test(this.host.fingerprint ?? ''))
+            fail('CTL_EXTERNAL_HOST', 'External callers require a registered, pinned host.');
+        const snapshot = JSON.stringify(this.host);
+        const session = await this.store.session(this.host, { storedOnly: true });
+        const assertCurrent = async () => {
+            if (JSON.stringify(this.store.get(this.host.name)) !== snapshot)
+                fail('CTL_EXTERNAL_PINS_CHANGED', 'Host or App approval changed.');
+            const current = await this.store.session(this.host, { storedOnly: true });
+            if (current.cookie !== session.cookie || current.token !== session.token)
+                fail('CTL_NOT_AUTHENTICATED', 'Stored login changed.', 2);
+        };
+        await assertCurrent();
+        const packages = await new CtlClient(this.store, this.host, this.request).inventory(session);
+        // Cached descriptors select an already approved credential recipient only.
+        // Neither cached schemas nor a new package may establish external authority.
+        const candidates = packages.filter(pkg => {
+            const approval = this.host.approved[pkg.id], cached = this.store.cache(this.host, pkg.id, pkg.version);
+            return approval?.version === pkg.version && approval.hash && cached?.hash === approval.hash &&
+                Object.hasOwn(cached.description?.payload?.external ?? {}, protocol);
+        });
+        if (candidates.length !== 1)
+            fail('CTL_EXTERNAL_PROTOCOL', 'Protocol must match exactly one pinned App.');
+        const pkg = candidates[0], approval = this.host.approved[pkg.id];
+        await assertCurrent();
+        const path = `/webman/3rdparty/${pkg.id}/cgi/api.cgi`;
+        const described = await this.request(path, { method: 'synopkgland.describe', params: {} }, session);
+        if (described?.success !== true)
+            fail('CTL_EXTERNAL_DENIED', 'App description refused.');
+        const app = validateDescriptor(described.data, pkg.id, pkg.version);
+        if (app.sha256 !== approval.hash)
+            fail('CTL_DESCRIPTION_CHANGED', 'Pinned App description changed.');
+        const entry = app.payload.external?.[protocol];
+        if (!entry)
+            fail('CTL_EXTERNAL_PROTOCOL', 'App does not declare this protocol.');
+        if (app.payload.transport.auth !== 'dsm-session')
+            fail('CTL_EXTERNAL_TRANSPORT', 'External callers require the DSM session transport.');
+        const pins = { package: { id: pkg.id, version: pkg.version }, descriptionSha256: app.sha256 };
+        const output = new SensitiveOutput({ carriers: [session.token, session.cookie, ...session.cookie.split(';').map(part => part.slice(part.indexOf('=') + 1).trim())] }, { type: 'object', properties: { carriers: { writeOnly: true } } });
+        const invoke = async (request) => {
+            await assertCurrent();
+            // The App must verify these pins and revision in its dispatch boundary,
+            // freshly authenticate an administrator and derive authority server-side.
+            const reply = await this.request(path, { method: entry.method, params: { ...request, ...pins } }, session);
+            if (reply?.success !== true)
+                fail('CTL_EXTERNAL_DENIED', 'Trusted external entry refused.');
+            const proof = reply.data?.verified;
+            if (!object(proof) || proof.protocol !== protocol || proof.package?.id !== pkg.id || proof.package?.version !== pkg.version ||
+                proof.descriptionSha256 !== app.sha256 || proof.user !== session.username || proof.administrator !== true ||
+                !revision(proof.revision) || request.action === 'call' && proof.revision !== request.revision ||
+                request.action === 'describe' && proof.revision !== reply.data?.data?.revision)
+                fail('CTL_EXTERNAL_VERIFICATION', 'External verification did not match the pinned request.', 5);
+            return reply.data.data;
+        };
+        const catalog = validateCatalog(await invoke({ protocol, action: 'describe' }));
+        if (input.action === 'describe')
+            return output.clean(catalog);
+        if (catalog.revision !== input.revision)
+            fail('CTL_EXTERNAL_REVISION', 'External tool revision changed.');
+        const tool = catalog.tools.find(tool => tool._meta.method === input.method);
+        if (!tool)
+            fail('CTL_EXTERNAL_METHOD', 'Method is not an external tool.');
+        if (!ajv.validate(tool.inputSchema, input.arguments))
+            fail('CTL_EXTERNAL_INPUT', 'Arguments do not match the current tool schema.', 3);
+        const sensitive = new SensitiveOutput(input.arguments, tool.inputSchema);
+        // Exactly one call attempt. Errors, lost replies and invalid results never replay it.
+        const result = await invoke(input);
+        if (!ajv.validate(tool.outputSchema, result))
+            fail('CTL_EXTERNAL_RESULT', 'External result does not match its schema.', 5);
+        return output.clean(sensitive.clean(result, tool.outputSchema));
+    }
+}
+export async function runExternal(argv, io = {}) {
+    const out = io.out ?? console.log;
+    try {
+        if (argv.length === 1 && argv[0] === '--help') {
+            out(JSON.stringify({ ok: true, data: { usage: USAGE } }));
+            return;
+        }
+        const values = new Map();
+        for (let i = 0; i < argv.length; i++) {
+            const flag = argv[i], key = flag.split('=')[0];
+            if (!['--protocol', '--host', '--input', '--json'].includes(key) || values.has(key))
+                fail('CTL_EXTERNAL_FLAGS', 'Invalid external options.', 3);
+            if (key === '--json') {
+                if (flag !== key)
+                    fail('CTL_EXTERNAL_FLAGS', 'Invalid JSON option.', 3);
+                values.set(key, 'true');
+                continue;
+            }
+            const value = flag.includes('=') ? flag.slice(key.length + 1) : argv[++i];
+            if (!value || value.startsWith('--'))
+                fail('CTL_EXTERNAL_FLAGS', 'Missing external option value.', 3);
+            values.set(key, value);
+        }
+        const protocol = values.get('--protocol'), hostName = values.get('--host');
+        if (values.size !== 4 || !protocol || !PROTOCOL.test(protocol) || !hostName || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(hostName) ||
+            values.get('--input') !== '-' || nasOptions().url || nasOptions().ca || nasOptions().strictTls)
+            fail('CTL_EXTERNAL_FLAGS', 'Use the fixed external command contract.', 3);
+        let raw;
+        try {
+            raw = readBounded(0);
+        }
+        catch {
+            return fail('CTL_EXTERNAL_INPUT', 'Cannot read bounded UTF-8 stdin.', 3);
+        }
+        const input = parseExternalRequest(raw, protocol);
+        const store = io.store ?? new CtlStore(), host = store.get(hostName);
+        const data = await new ExternalClient(store, host, io.requestFor?.(host)).execute(protocol, input);
+        const line = JSON.stringify({ ok: true, data });
+        if (Buffer.byteLength(line + '\n') > LIMIT)
+            fail('CTL_EXTERNAL_OUTPUT', 'External output exceeds 1 MiB.', 5);
+        out(line);
+    }
+    catch (error) {
+        const e = ctlError(error);
+        // Never echo upstream messages, input, session carriers or exception text.
+        out(JSON.stringify({ ok: false, error: { code: e.code, message: 'External request refused.', hint: HINT } }));
+        process.exitCode = e.exitCode;
+    }
+}

package/dist/error-registry.js

@@ -553,6 +553,11 @@ export const ERROR_REGISTRY = {
             description: "ui.window does not give a valid DSM window size.",
             suggestion: "Give width and height as whole numbers from 320 to 3840 and 240 to 2160, keep minWidth and minHeight (700 and 420 by default) no larger than them, and write only the fields you change.",
         },
+        STANDALONE_UI_BANNER_INVALID: {
+            code: "STANDALONE_UI_BANNER_INVALID",
+            description: "ui.banner is neither shown nor hidden.",
+            suggestion: "Set ui.banner to hidden to drop DSM's banner from the App's standalone page, or omit it to keep the banner.",
+        },
         STANDALONE_UI_BUILD_FAILED: {
             code: "STANDALONE_UI_BUILD_FAILED",
             description: "The UI build command failed.",

package/dist/nas/store.d.ts

@@ -44,7 +44,9 @@ export declare class CtlStore {
     save(host: Host): void;
     add(host: Host, session: DsmSession): Promise<void>;
     trust(host: Host): HostTls;
-    session(host: Host): Promise<DsmSession>;
+    session(host: Host, options?: {
+        storedOnly?: boolean;
+    }): Promise<DsmSession>;
     cacheRoot(host: Host): string;
     cacheFile(host: Host, pkg: string, version: string): string;
     cache(host: Host, pkg: string, version: string): any | null;

package/dist/nas/store.js

@@ -94,9 +94,9 @@ export class CtlStore {
             } },
             record: (fingerprint) => { host.fingerprint = fingerprint; this.save(host); }, warn: override.warn };
     }
-    async session(host) {
+    async session(host, options = {}) {
         let session;
-        if (process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
+        if (!options.storedOnly && process.env.DSM_USERNAME && process.env.DSM_PASSWORD) {
             if (process.env.DSM_USERNAME !== host.username)
                 throw new CtlError('CTL_CREDENTIAL_MISMATCH', 'Automation account differs from the registered host.', 'Use the registered account or a separately named host.', 2);
             session = await loginDsm(host.origin, host.username, process.env.DSM_PASSWORD, { remember: false, otp: async () => process.env.DSM_OTP ?? '', request: createRequest(host.origin, 30000, undefined, this.trust(host)) });

package/dist/standalone/api-description.js

@@ -34,6 +34,7 @@ export async function buildApiDescription(m, bridgeMethods, run) {
         throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Invalid registry snapshot.');
     const registry = new Map(methods.map(item => [item.method, item.permission]));
     const rawHTTP = new Set(methods.filter(item => item.kind === 'http').map(item => item.method));
+    const nonRPC = new Set(methods.filter(item => item.kind && item.kind !== 'json').map(item => item.method));
     // Identity transport routes are outside the business registry but have immutable SDK ownership.
     if (m.capabilities.identity) {
         registry.set('identity.session', 'public');
@@ -41,6 +42,16 @@ export async function buildApiDescription(m, bridgeMethods, run) {
     }
     const bindings = {};
     const commands = {};
+    if (m.ctl.external) {
+        if (m.capabilities.identity)
+            throw new StandaloneBuildError('CTL_EXTERNAL_TRANSPORT', 'External entries require the DSM session transport.');
+        for (const entry of Object.values(m.ctl.external)) {
+            if (!entry || typeof entry.method !== 'string' || !registry.has(entry.method) || nonRPC.has(entry.method) || m.entry !== 'admin-only' && registry.get(entry.method) !== 'administrators')
+                throw new StandaloneBuildError('CTL_EXTERNAL_ENTRY', 'External entries require registered administrator RPC methods.');
+            registry.set(entry.method, 'administrators');
+            bindings[entry.method] = { permission: 'administrators', effect: 'destructive' };
+        }
+    }
     const weights = { read: 0, write: 1, destructive: 2 };
     for (const [id, declared] of Object.entries(m.ctl.commands)) {
         const command = structuredClone(declared);
@@ -66,7 +77,7 @@ export async function buildApiDescription(m, bridgeMethods, run) {
         for (const method of ['identity.session', 'identity.logout'])
             bindings[method] = { permission: 'public', effect: 'write' };
     }
-    const description = makeDescriptor({ package: { id: m.package, version: m.spkVersion, displayName: m.displayname }, aliases: m.ctl.aliases ?? [m.package.toLowerCase()], provenance: { developedBy: m.ctl.developedBy ?? 'unknown', generator: 'synopkgland-cli' }, entry: m.entry ?? 'policy', transport: { path: `/webman/3rdparty/${m.package}/cgi/api.cgi`, auth: m.capabilities.identity ? 'dsm-app-session' : 'dsm-session' }, commands, bindings });
+    const description = makeDescriptor({ package: { id: m.package, version: m.spkVersion, displayName: m.displayname }, aliases: m.ctl.aliases ?? [m.package.toLowerCase()], provenance: { developedBy: m.ctl.developedBy ?? 'unknown', generator: 'synopkgland-cli' }, entry: m.entry ?? 'policy', transport: { path: `/webman/3rdparty/${m.package}/cgi/api.cgi`, auth: m.capabilities.identity ? 'dsm-app-session' : 'dsm-session' }, commands, bindings, ...(m.ctl.external ? { external: m.ctl.external } : {}) });
     try {
         return { description: validateDescriptor(description, m.package, m.spkVersion), registry: Object.fromEntries(registry) };
     }

package/dist/standalone/dsm-window.js

@@ -225,6 +225,7 @@ export function renderWindowScript(manifest, assetVersion, icons = packageIcons(
     const p = JSON.stringify(pkg);
     const root = manifest.executor ? renderRootParts(ns, manifest) : undefined;
     const size = manifest.ui.window ?? DEFAULT_WINDOW;
+    const hideBanner = manifest.ui.banner === "hidden";
     const requestTimeout = requestTimeoutSeconds(manifest.backend) * 1000;
     const clientMargin = appSdkTimeouts(manifest.backend).browserMarginMs;
     const sessionRuntime = appSdkSessionRuntime(manifest.backend);
@@ -473,7 +474,15 @@ ${ns}.prepareFullPage = function (title) {
   favicon.href = ${ns}.appIcon;
 };
 
-${windowResumesOIDC(manifest) ? `${ns}.resumeOIDC = ${oidcResumeRuntime(pkg, Object.values(manifest.identityGateway.listen).filter((p) => typeof p === "number"))};` : ""}
+${hideBanner ? `// ui.banner: hidden. DSM's own "Hide banner" class on a standalone page; on the
+// desktop it would hide the window's title bar, so the window keeps it there.
+${ns}.hideBanner = function (config) {
+  if (!${ns}.fullPage()) return config;
+  config = Ext.apply({}, config);
+  config.cls = (config.cls ? config.cls + " " : "") + "sds-standalone-main-window--no-banner";
+  return config;
+};
+` : ""}${windowResumesOIDC(manifest) ? `${ns}.resumeOIDC = ${oidcResumeRuntime(pkg, Object.values(manifest.identityGateway.listen).filter((p) => typeof p === "number"))};` : ""}
 
 // DSM reopens a window at the size it was last left at, even one saved on a
 // larger screen, and only moves a window that does not fit: keep it inside.
@@ -495,8 +504,10 @@ Ext.define(${JSON.stringify(`${ns}.MainWindow`)}, {
     this.callParent([${ns}.fitDesktop(Ext.apply({
       width: ${size.width}, height: ${size.height}, minWidth: ${ns}.fullPage() ? ${FULL_PAGE_MIN_WIDTH} : ${size.minWidth}, minHeight: ${size.minHeight}, layout: "fit",
       ${root ? root.html : `html: '<div class="dsmapp-root" style="height:100%"></div>'`}
-    }, config))]);
-  },
+    }, ${hideBanner ? `${ns}.hideBanner(config)` : "config"}))]);
+  },${hideBanner ? `
+  // DSM draws the banner unless its global "Hide banner" is on; skip it for this App alone.
+  genIndPortHeader: function () {},` : ""}
   getRestoreSizePos: function (config) {
     return ${ns}.fitDesktop(Ext.apply({ width: config.width, height: config.height }, this.callParent(arguments)));
   },

package/dist/standalone/host-adapter.d.ts

@@ -1,5 +1,5 @@
 export type { HostAdapter, HostTitleResult, HostRequestResult, HostURLResult, HostEvent, HostSubscriptionResult, HostFileNavigationResult, HostUnsupportedResult } from "./host-types.js";
-export declare const HOST_ADAPTER_RUNTIME = "function inspectHostPlatform(ctx) {\n  ctx = ctx || {};\n  var web = typeof window !== \"undefined\";\n  var host = false;\n  try {\n    host = !!(web && ctx.appWindow && typeof SYNO !== \"undefined\" &&\n      SYNO.SDS && typeof SYNO.SDS.AppWindow === \"function\" &&\n      ctx.appWindow instanceof SYNO.SDS.AppWindow);\n  } catch (error) {\n    // An unsupported host constructor must not break a standalone shell.\n  }\n  function read(key) {\n    if (!host || typeof _S !== \"function\") return null;\n    try { return _S(key); } catch (error) { return null; }\n  }\n  function text(value) {\n    return typeof value === \"string\" && /\\S/.test(value) ? value : null;\n  }\n  function versionPart(value) {\n    if (typeof value === \"number\") {\n      if (!isFinite(value) || value < 0 || Math.floor(value) !== value) return null;\n      value = String(value);\n    }\n    return typeof value === \"string\" && value.length > 0 && !/\\D/.test(value) ? value : null;\n  }\n  var standalone = read(\"standalone\");\n  var language = text(read(\"lang\"));\n  var major = versionPart(read(\"majorversion\"));\n  var minor = versionPart(read(\"minorversion\"));\n  var fullVersion = text(read(\"fullversion\"));\n  return Object.freeze({\n    web: web,\n    host: host ? \"dsm\" : web ? \"standalone-web\" : \"unavailable\",\n    dsmStandalone: typeof standalone === \"boolean\" ? standalone : null,\n    dsmLanguage: language,\n    appLocale: text(ctx.locale),\n    systemVersion: major !== null && minor !== null ? major + \".\" + minor : null,\n    fullVersion: fullVersion,\n    theme: null\n  });\n}\n\nfunction requestHostFileNavigation(launch, path, isDirectory) {\n  if (typeof path !== \"string\" || path.length > 4096 || path.charAt(0) !== \"/\" ||\n    /[\\x00-\\x1f\\x7f\\\\]/.test(path)) return { status: \"invalid-input\" };\n  var volume = /^\\/volume(?:USB|SATA)?[0-9]+(?=\\/|$)/.exec(path);\n  if (volume) path = path.slice(volume[0].length);\n  var parts = path.split(\"/\");\n  if (parts.length < 2 || parts.slice(1).some(function (part) {\n    return !part || part === \".\" || part === \"..\";\n  })) return { status: \"invalid-input\" };\n  var result = launch(\"SYNO.SDS.App.FileStation3.Instance\", isDirectory ? { opendir: path } : { openfile: path });\n  if (result.status !== \"requested\") return result;\n  return { status: \"requested\", action: isDirectory ? \"locate-folder\" : \"highlight-file\" };\n}\n\n\nvar REVEAL_RECOVERY_TIMEOUT_MS = 5000;\nvar REVEAL_RECOVERY_POLL_MS = 100;\nvar REVEAL_RECOVERY_QUIET_MS = 300;\nvar hostFileRevealOwners = null, hostFileRevealSequence = 0;\ntry { if (typeof WeakMap === \"function\") hostFileRevealOwners = new WeakMap(); } catch (error) {}\nfunction createHostFileRevealRecovery(path, canAct) {\n  var active = true, accepted = false, win = null, dom = null, tuple = null;\n  var poll = null, deadline = null, removers = [], reached = false, pending = 0;\n  var previous = null, quietSince = null, expires = 0, order = ++hostFileRevealSequence;\n  var parent = path.slice(0, path.lastIndexOf(\"/\"));\n  function cancel() {\n    if (!active) return;\n    active = false;\n    try { if (poll !== null) clearTimeout(poll); } catch (error) {}\n    try { if (deadline !== null) clearTimeout(deadline); } catch (error) {}\n    poll = deadline = null;\n    removers.splice(0).forEach(function (remove) { try { remove(); } catch (error) {} });\n    try {\n      if (win && hostFileRevealOwners.get(win).order === order) {\n        // Preserve ordering for a late older callback, without retaining its closures.\n        hostFileRevealOwners.set(win, { order: order, cancel: null });\n      }\n    } catch (error) {}\n    win = dom = tuple = previous = null;\n  }\n  function requireMethods(target, names) {\n    if (!target || names.some(function (name) { return typeof target[name] !== \"function\"; })) throw new Error(\"unsupported receiver\");\n  }\n  function guard(fn) {\n    return function () {\n      if (!active) return;\n      try { fn.apply(null, arguments); } catch (error) { cancel(); }\n    };\n  }\n  function listen(target, event, fn) {\n    requireMethods(target, [\"on\", \"un\"]);\n    var handler = guard(fn), remove = target.un;\n    removers.push(function () { remove.call(target, event, handler, target); });\n    target.on(event, handler, target);\n  }\n  function resetQuiet() { previous = null; quietSince = null; }\n  function inspect() {\n    requireMethods(win, [\"getPanelInstance\", \"getEl\", \"on\", \"un\"]);\n    if (win.isDestroyed || win.destroyed || !canAct()) { cancel(); return null; }\n    var element = win.getEl(), nextDom = element && element.dom;\n    if (!nextDom) { if (dom) cancel(); return null; }\n    requireMethods(nextDom, [\"addEventListener\", \"removeEventListener\"]);\n    if (dom && nextDom !== dom) { cancel(); return null; }\n    if (!dom) {\n      dom = nextDom;\n      [\"pointerdown\", \"mousedown\", \"touchstart\", \"keydown\", \"wheel\", \"click\", \"input\"].forEach(function (event) {\n        var remove = dom.removeEventListener, handler = guard(cancel), target = dom;\n        removers.push(function () { remove.call(target, event, handler, true); });\n        dom.addEventListener(event, handler, true);\n      });\n    }\n    var panel = win.getPanelInstance();\n    if (!panel) { if (tuple) cancel(); return null; }\n    requireMethods(panel, [\"getCurrentDir\", \"on\", \"un\"]);\n    var view = panel.activeView, store = panel.activeDS;\n    requireMethods(view, [\"getStore\", \"getSelectionModel\", \"scrollToItem\"]);\n    requireMethods(store, [\"on\", \"un\", \"indexOfId\", \"getAt\", \"getCount\"]);\n    var model = view.getSelectionModel();\n    requireMethods(model, [\"on\", \"un\", \"getSelections\", \"selectRow\"]);\n    if (view.getStore() !== store || panel.isDestroyed || store.isDestroyed || model.isDestroyed) { cancel(); return null; }\n    if (tuple && (tuple.panel !== panel || tuple.view !== view || tuple.store !== store || tuple.model !== model)) { cancel(); return null; }\n    if (!tuple) {\n      tuple = { panel: panel, view: view, store: store, model: model };\n      listen(panel, \"destroy\", cancel);\n      listen(panel, \"onNodeClick\", function (node) {\n        if (!node || !node.attributes || (reached && node.attributes.path !== parent)) cancel();\n      });\n      listen(store, \"beforeload\", function () {\n        pending++; resetQuiet(); inspect();\n      });\n      listen(store, \"load\", function () {\n        if (pending > 0) pending--;\n        resetQuiet(); check();\n      });\n      [\"exception\", \"loadexception\", \"destroy\"].forEach(function (event) { listen(store, event, cancel); });\n      listen(model, \"selectionchange\", function () { resetQuiet(); check(); });\n    }\n    var dir = panel.getCurrentDir(), params = store.baseParams;\n    // New File Station panels expose their APIs before the first directory is set.\n    // Keep the bound receiver guards and original deadline while startup finishes.\n    if (!reached && dir === undefined && (!params || params.folder_path === undefined)) return null;\n    if (!params || typeof params.folder_path !== \"string\") throw new Error(\"unsupported store path\");\n    // Native reconfigure/selection events can precede the store's path assignment.\n    if (dir === parent && params.folder_path === parent) reached = true;\n    if (reached && (dir !== parent || params.folder_path !== parent)) { cancel(); return null; }\n    var selections = model.getSelections();\n    if (!Array.isArray(selections)) throw new Error(\"unsupported selection\");\n    if (selections.some(function (record) { return !record || record.id !== path; })) { cancel(); return null; }\n    var index = store.indexOfId(path), count = store.getCount();\n    if (!Number.isInteger(index) || index < -1 || !Number.isInteger(count) || count < 0) throw new Error(\"unsupported store index\");\n    var record = index >= 0 ? store.getAt(index) : null;\n    if (index >= 0 && (!record || record.id !== path || index >= count)) throw new Error(\"inconsistent store\");\n    return { dir: dir, folder: params.folder_path, count: count, index: index, record: record, selected: selections.length > 0 };\n  }\n  function check() {\n    if (!active) return;\n    if (Date.now() >= expires || !canAct()) { cancel(); return; }\n    if (!win) return;\n    var state = inspect();\n    if (!active || !state) return;\n    if (pending || state.dir !== parent || state.folder !== parent || state.index < 0) { resetQuiet(); return; }\n    if (!previous || Object.keys(state).some(function (key) { return state[key] !== previous[key]; })) {\n      previous = state; quietSince = Date.now();\n    }\n    if (Date.now() - quietSince < REVEAL_RECOVERY_QUIET_MS) return;\n    var target = tuple, receiverWindow = win;\n    cancel(); // Release every observer before the one permitted selection mutation.\n    if (state.selected || !canAct()) return;\n    target.model.selectRow(state.index);\n    if (canAct() && !receiverWindow.isDestroyed && receiverWindow.getPanelInstance() === target.panel &&\n        target.panel.activeView === target.view && target.panel.activeDS === target.store &&\n        target.view.getSelectionModel() === target.model) target.view.scrollToItem(state.index);\n  }\n  function tick() {\n    poll = null;\n    try {\n      check();\n      if (active) poll = setTimeout(tick, REVEAL_RECOVERY_POLL_MS);\n    } catch (error) { cancel(); }\n  }\n  function receive(instance) {\n    if (!active || accepted) return;\n    accepted = true;\n    try {\n      if (Date.now() >= expires || !canAct()) { cancel(); return; }\n      win = instance && instance.window;\n      requireMethods(win, [\"getPanelInstance\", \"getEl\", \"on\", \"un\"]);\n      var owner = hostFileRevealOwners.get(win);\n      if (owner && owner.order > order) { cancel(); return; }\n      if (owner && owner.cancel) owner.cancel();\n      hostFileRevealOwners.set(win, { order: order, cancel: cancel });\n      [\"beforeclose\", \"close\", \"beforedestroy\", \"destroy\", \"hide\"].forEach(function (event) { listen(win, event, cancel); });\n      check();\n    } catch (error) { cancel(); }\n  }\n  try {\n    if (!parent || !hostFileRevealOwners || typeof setTimeout !== \"function\" || typeof clearTimeout !== \"function\" || typeof Date.now !== \"function\") {\n      cancel();\n    } else {\n      expires = Date.now() + REVEAL_RECOVERY_TIMEOUT_MS;\n      deadline = setTimeout(cancel, REVEAL_RECOVERY_TIMEOUT_MS);\n      poll = setTimeout(tick, REVEAL_RECOVERY_POLL_MS);\n    }\n  } catch (error) { cancel(); }\n  return { receive: receive, cancel: cancel };\n}\n\nfunction createHostAdapter(ctx) {\n  ctx = ctx || {};\n  var disposed = false, subscriptions = [], revealRecovery = null;\n  function launchApp(appId, config, receiverCallback) {\n    if (disposed) return { status: \"unavailable\" };\n    if (typeof appId !== \"string\" || !appId || /\\s/.test(appId)) return { status: \"invalid-input\" };\n    try {\n      if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n      var sds = SYNO.SDS, map = sds.Config && sds.Config.FnMap, notifier = sds.StatusNotifier;\n      if (typeof sds.AppLaunch !== \"function\" || !map ||\n          !Object.prototype.hasOwnProperty.call(map, appId) || !map[appId] || !notifier ||\n          typeof notifier.isAppEnabled !== \"function\" || !notifier.isAppEnabled(appId) ||\n          typeof notifier.isAppLaunchable !== \"function\" || !notifier.isAppLaunchable(appId)) {\n        return { status: \"unsupported\" };\n      }\n      if (receiverCallback) sds.AppLaunch(appId, config, undefined, receiverCallback);\n      else sds.AppLaunch(appId, config);\n      return { status: \"requested\" };\n    } catch (error) { return { status: \"failed\" }; }\n  }\n  function navigateFileStation(path, isDirectory) {\n    if (disposed) return { status: \"unavailable\" };\n    if (revealRecovery) revealRecovery.cancel();\n    revealRecovery = null;\n    function launchFile(appId, config) {\n      if (isDirectory) return launchApp(appId, config);\n      var recovery = createHostFileRevealRecovery(config.openfile, function () { return !disposed && revealRecovery === recovery; });\n      revealRecovery = recovery;\n      var result = launchApp(appId, config, recovery.receive);\n      if (result.status !== \"requested\") recovery.cancel();\n      return result;\n    }\n    return requestHostFileNavigation(launchFile, path, isDirectory);\n  }\n  function unsupportedOperation() { return { status: disposed ? \"unavailable\" : \"unsupported\" }; }\n  return Object.freeze({\n    platform: function () {\n      if (!disposed) return inspectHostPlatform(ctx);\n      return Object.freeze({\n        web: typeof window !== \"undefined\", host: \"unavailable\",\n        dsmStandalone: null, dsmLanguage: null, appLocale: null,\n        systemVersion: null, fullVersion: null, theme: null\n      });\n    },\n    setTitle: function (title) {\n      if (disposed) return { status: \"unavailable\" };\n      if (typeof title !== \"string\") return { status: \"invalid-input\" };\n      try {\n        var platform = inspectHostPlatform(ctx);\n        if (platform.host === \"dsm\") {\n          if (typeof ctx.appWindow.setTitle !== \"function\") return { status: \"unsupported\" };\n          ctx.appWindow.setTitle(title, undefined, true);\n          return { status: \"ok\", target: \"dsm-window\" };\n        }\n        if (!platform.web) return { status: \"unavailable\" };\n        if (typeof document === \"undefined\") return { status: \"unsupported\" };\n        document.title = title;\n        return { status: \"ok\", target: \"document\" };\n      } catch (error) {\n        return { status: \"failed\" };\n      }\n    },\n    activateWindow: function () {\n      if (disposed) return { status: \"unavailable\" };\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        var win = ctx.appWindow;\n        var activate = typeof win.toFront === \"function\" ? win.toFront : win.activate;\n        if (typeof activate !== \"function\") return { status: \"unsupported\" };\n        // DSM minimizes by hiding; show preserves maximized geometry, unlike restore.\n        if (win.hidden === true || win.minimized === true ||\n            (typeof win.isVisible === \"function\" && win.isVisible() === false)) {\n          if (typeof win.show !== \"function\") return { status: \"unsupported\" };\n          win.show();\n        }\n        activate.call(win);\n        return { status: \"requested\" };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    requestClose: function () {\n      if (disposed) return { status: \"unavailable\" };\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        var win = ctx.appWindow;\n        // DSM returns a short-circuit value; only truthy means standalone main.\n        if (typeof win.close !== \"function\" || typeof win.isStandaloneMainWindow !== \"function\" ||\n            win.isStandaloneMainWindow()) return { status: \"unsupported\" };\n        if (win.canClose === false) return { status: \"blocked\" };\n        win.close();\n        return { status: \"requested\" };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    openApp: function (appId) { return launchApp(appId, {}); },\n    openURL: function (raw) {\n      if (disposed || typeof window === \"undefined\") return { status: \"unavailable\" };\n      if (typeof raw !== \"string\" || !raw || /[\\s\\x00-\\x1f\\x7f]/.test(raw)) return { status: \"invalid-input\" };\n      if (typeof URL !== \"function\") return { status: \"unsupported\" };\n      var url;\n      try { url = new URL(raw); } catch (error) { return { status: \"invalid-input\" }; }\n      if ((url.protocol !== \"http:\" && url.protocol !== \"https:\") || url.username || url.password) return { status: \"invalid-input\" };\n      if (typeof window.open !== \"function\") return { status: \"unsupported\" };\n      try {\n        var opened = window.open(url.href, \"_blank\", \"noopener,noreferrer\");\n        return { status: \"requested\", windowHandleAvailable: !!opened };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    openFileManager: function (path) { return navigateFileStation(path, true); },\n    revealFile: function (path) { return navigateFileStation(path, false); },\n    openFile: unsupportedOperation,\n    showFileDetails: unsupportedOperation,\n    openAppSetting: unsupportedOperation,\n    subscribe: function (event, listener) {\n      if (disposed) return { status: \"unavailable\" };\n      if (typeof listener !== \"function\") return { status: \"invalid-input\" };\n      if (event !== \"window-resize\") return { status: \"unsupported\" };\n      var win, callback = listener, active = true;\n      function handler() { if (!disposed && callback) callback(); }\n      function unsubscribe() {\n        if (!active) return;\n        active = false;\n        callback = null;\n        var target = win;\n        win = null;\n        var index = subscriptions.indexOf(unsubscribe);\n        if (index !== -1) subscriptions.splice(index, 1);\n        try { if (target) target.un(\"resize\", handler, target); } catch (error) {}\n      }\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        win = ctx.appWindow;\n        if (typeof win.on !== \"function\" || typeof win.un !== \"function\") return { status: \"unsupported\" };\n        subscriptions.push(unsubscribe);\n        win.on(\"resize\", handler, win);\n        if (disposed) return { status: \"unavailable\" };\n        return Object.freeze({ status: \"subscribed\", dispose: unsubscribe });\n      } catch (error) {\n        unsubscribe();\n        return { status: \"failed\" };\n      }\n    },\n    dispose: function () {\n      if (disposed) return;\n      disposed = true;\n      if (revealRecovery) revealRecovery.cancel();\n      revealRecovery = null;\n      subscriptions.slice().forEach(function (unsubscribe) { unsubscribe(); });\n      ctx = null;\n    }\n  });\n}";
+export declare const HOST_ADAPTER_RUNTIME = "function inspectHostPlatform(ctx) {\n  ctx = ctx || {};\n  var web = typeof window !== \"undefined\";\n  var host = false;\n  try {\n    host = !!(web && ctx.appWindow && typeof SYNO !== \"undefined\" &&\n      SYNO.SDS && typeof SYNO.SDS.AppWindow === \"function\" &&\n      ctx.appWindow instanceof SYNO.SDS.AppWindow);\n  } catch (error) {\n    // An unsupported host constructor must not break a standalone shell.\n  }\n  function read(key) {\n    if (!host || typeof _S !== \"function\") return null;\n    try { return _S(key); } catch (error) { return null; }\n  }\n  function text(value) {\n    return typeof value === \"string\" && /\\S/.test(value) ? value : null;\n  }\n  function versionPart(value) {\n    if (typeof value === \"number\") {\n      if (!isFinite(value) || value < 0 || Math.floor(value) !== value) return null;\n      value = String(value);\n    }\n    return typeof value === \"string\" && value.length > 0 && !/\\D/.test(value) ? value : null;\n  }\n  var standalone = read(\"standalone\");\n  var language = text(read(\"lang\"));\n  var major = versionPart(read(\"majorversion\"));\n  var minor = versionPart(read(\"minorversion\"));\n  var fullVersion = text(read(\"fullversion\"));\n  return Object.freeze({\n    web: web,\n    host: host ? \"dsm\" : web ? \"standalone-web\" : \"unavailable\",\n    dsmStandalone: typeof standalone === \"boolean\" ? standalone : null,\n    dsmLanguage: language,\n    appLocale: text(ctx.locale),\n    systemVersion: major !== null && minor !== null ? major + \".\" + minor : null,\n    fullVersion: fullVersion,\n    theme: null\n  });\n}\n\nfunction requestHostFileNavigation(launch, path, isDirectory) {\n  if (typeof path !== \"string\" || path.length > 4096 || path.charAt(0) !== \"/\" ||\n    /[\\x00-\\x1f\\x7f\\\\]/.test(path)) return { status: \"invalid-input\" };\n  var volume = /^\\/volume(?:USB|SATA)?[0-9]+(?=\\/|$)/.exec(path);\n  if (volume) path = path.slice(volume[0].length);\n  var parts = path.split(\"/\");\n  if (parts.length < 2 || parts.slice(1).some(function (part) {\n    return !part || part === \".\" || part === \"..\";\n  })) return { status: \"invalid-input\" };\n  var result = launch(\"SYNO.SDS.App.FileStation3.Instance\", isDirectory ? { opendir: path } : { openfile: path });\n  if (result.status !== \"requested\") return result;\n  return { status: \"requested\", action: isDirectory ? \"locate-folder\" : \"highlight-file\" };\n}\n\n\nvar REVEAL_RECOVERY_TIMEOUT_MS = 5000;\nvar REVEAL_RECOVERY_POLL_MS = 100;\nvar REVEAL_RECOVERY_QUIET_MS = 300;\nvar hostFileRevealOwners = null, hostFileRevealSequence = 0;\ntry { if (typeof WeakMap === \"function\") hostFileRevealOwners = new WeakMap(); } catch (error) {}\nfunction createHostFileRevealRecovery(path, canAct) {\n  var active = true, accepted = false, win = null, dom = null, tuple = null;\n  var poll = null, deadline = null, removers = [], reached = false, pending = 0;\n  var previous = null, quietSince = null, expires = 0, order = ++hostFileRevealSequence;\n  var parent = path.slice(0, path.lastIndexOf(\"/\"));\n  function cancel() {\n    if (!active) return;\n    active = false;\n    try { if (poll !== null) clearTimeout(poll); } catch (error) {}\n    try { if (deadline !== null) clearTimeout(deadline); } catch (error) {}\n    poll = deadline = null;\n    removers.splice(0).forEach(function (remove) { try { remove(); } catch (error) {} });\n    try {\n      if (win && hostFileRevealOwners.get(win).order === order) {\n        // Preserve ordering for a late older callback, without retaining its closures.\n        hostFileRevealOwners.set(win, { order: order, cancel: null });\n      }\n    } catch (error) {}\n    win = dom = tuple = previous = null;\n  }\n  function requireMethods(target, names) {\n    if (!target || names.some(function (name) { return typeof target[name] !== \"function\"; })) throw new Error(\"unsupported receiver\");\n  }\n  function guard(fn) {\n    return function () {\n      if (!active) return;\n      try { fn.apply(null, arguments); } catch (error) { cancel(); }\n    };\n  }\n  function listen(target, event, fn) {\n    requireMethods(target, [\"on\", \"un\"]);\n    var handler = guard(fn), remove = target.un;\n    removers.push(function () { remove.call(target, event, handler, target); });\n    target.on(event, handler, target);\n  }\n  function resetQuiet() { previous = null; quietSince = null; }\n  function inspect() {\n    requireMethods(win, [\"getPanelInstance\", \"getEl\", \"on\", \"un\"]);\n    if (win.isDestroyed || win.destroyed || !canAct()) { cancel(); return null; }\n    var element = win.getEl(), nextDom = element && element.dom;\n    if (!nextDom) { if (dom) cancel(); return null; }\n    requireMethods(nextDom, [\"addEventListener\", \"removeEventListener\"]);\n    if (dom && nextDom !== dom) { cancel(); return null; }\n    if (!dom) {\n      dom = nextDom;\n      [\"pointerdown\", \"mousedown\", \"touchstart\", \"keydown\", \"wheel\", \"click\", \"input\"].forEach(function (event) {\n        var remove = dom.removeEventListener, handler = guard(cancel), target = dom;\n        removers.push(function () { remove.call(target, event, handler, true); });\n        dom.addEventListener(event, handler, true);\n      });\n    }\n    var panel = win.getPanelInstance();\n    if (!panel) { if (tuple) cancel(); return null; }\n    requireMethods(panel, [\"getCurrentDir\", \"on\", \"un\"]);\n    var view = panel.activeView, store = panel.activeDS;\n    requireMethods(view, [\"getStore\", \"getSelectionModel\", \"scrollToItem\"]);\n    requireMethods(store, [\"on\", \"un\", \"indexOfId\", \"getAt\", \"getCount\"]);\n    var model = view.getSelectionModel();\n    requireMethods(model, [\"on\", \"un\", \"getSelections\", \"selectRow\"]);\n    if (view.getStore() !== store || panel.isDestroyed || store.isDestroyed || model.isDestroyed) { cancel(); return null; }\n    if (tuple && (tuple.panel !== panel || tuple.view !== view || tuple.store !== store || tuple.model !== model)) { cancel(); return null; }\n    if (!tuple) {\n      tuple = { panel: panel, view: view, store: store, model: model };\n      listen(panel, \"destroy\", cancel);\n      listen(panel, \"onNodeClick\", function (node) {\n        if (!node || !node.attributes || (reached && node.attributes.path !== parent)) cancel();\n      });\n      listen(store, \"beforeload\", function () {\n        pending++; resetQuiet(); inspect();\n      });\n      listen(store, \"load\", function () {\n        if (pending > 0) pending--;\n        resetQuiet(); check();\n      });\n      [\"exception\", \"loadexception\", \"destroy\"].forEach(function (event) { listen(store, event, cancel); });\n      listen(model, \"selectionchange\", function () { resetQuiet(); check(); });\n    }\n    var dir = panel.getCurrentDir(), params = store.baseParams;\n    // New File Station panels expose their APIs before the first directory is set.\n    // Keep the bound receiver guards and original deadline while startup finishes.\n    if (!reached && dir === undefined && (!params || params.folder_path === undefined)) return null;\n    if (!params || typeof params.folder_path !== \"string\") throw new Error(\"unsupported store path\");\n    // Native reconfigure/selection events can precede the store's path assignment.\n    if (dir === parent && params.folder_path === parent) reached = true;\n    if (reached && (dir !== parent || params.folder_path !== parent)) { cancel(); return null; }\n    var selections = model.getSelections();\n    if (!Array.isArray(selections)) throw new Error(\"unsupported selection\");\n    if (selections.some(function (record) { return !record || record.id !== path; })) { cancel(); return null; }\n    var index = store.indexOfId(path), count = store.getCount();\n    if (!Number.isInteger(index) || index < -1 || !Number.isInteger(count) || count < 0) throw new Error(\"unsupported store index\");\n    var record = index >= 0 ? store.getAt(index) : null;\n    if (index >= 0 && (!record || record.id !== path || index >= count)) throw new Error(\"inconsistent store\");\n    return { dir: dir, folder: params.folder_path, count: count, index: index, record: record, selected: selections.length > 0 };\n  }\n  function check() {\n    if (!active) return;\n    if (Date.now() >= expires || !canAct()) { cancel(); return; }\n    if (!win) return;\n    var state = inspect();\n    if (!active || !state) return;\n    if (pending || state.dir !== parent || state.folder !== parent || state.index < 0) { resetQuiet(); return; }\n    if (!previous || Object.keys(state).some(function (key) { return state[key] !== previous[key]; })) {\n      previous = state; quietSince = Date.now();\n    }\n    if (Date.now() - quietSince < REVEAL_RECOVERY_QUIET_MS) return;\n    var target = tuple, receiverWindow = win;\n    cancel(); // Release every observer before the one permitted selection mutation.\n    if (state.selected || !canAct()) return;\n    target.model.selectRow(state.index);\n    if (canAct() && !receiverWindow.isDestroyed && receiverWindow.getPanelInstance() === target.panel &&\n        target.panel.activeView === target.view && target.panel.activeDS === target.store &&\n        target.view.getSelectionModel() === target.model) target.view.scrollToItem(state.index);\n  }\n  function tick() {\n    poll = null;\n    try {\n      check();\n      if (active) poll = setTimeout(tick, REVEAL_RECOVERY_POLL_MS);\n    } catch (error) { cancel(); }\n  }\n  function receive(instance) {\n    if (!active || accepted) return;\n    accepted = true;\n    try {\n      if (Date.now() >= expires || !canAct()) { cancel(); return; }\n      win = instance && instance.window;\n      requireMethods(win, [\"getPanelInstance\", \"getEl\", \"on\", \"un\"]);\n      var owner = hostFileRevealOwners.get(win);\n      if (owner && owner.order > order) { cancel(); return; }\n      if (owner && owner.cancel) owner.cancel();\n      hostFileRevealOwners.set(win, { order: order, cancel: cancel });\n      [\"beforeclose\", \"close\", \"beforedestroy\", \"destroy\", \"hide\"].forEach(function (event) { listen(win, event, cancel); });\n      check();\n    } catch (error) { cancel(); }\n  }\n  try {\n    if (!parent || !hostFileRevealOwners || typeof setTimeout !== \"function\" || typeof clearTimeout !== \"function\" || typeof Date.now !== \"function\") {\n      cancel();\n    } else {\n      expires = Date.now() + REVEAL_RECOVERY_TIMEOUT_MS;\n      deadline = setTimeout(cancel, REVEAL_RECOVERY_TIMEOUT_MS);\n      poll = setTimeout(tick, REVEAL_RECOVERY_POLL_MS);\n    }\n  } catch (error) { cancel(); }\n  return { receive: receive, cancel: cancel };\n}\n\nfunction createHostAdapter(ctx) {\n  ctx = ctx || {};\n  var disposed = false, subscriptions = [], revealRecovery = null;\n  function launchApp(appId, config, receiverCallback) {\n    if (disposed) return { status: \"unavailable\" };\n    if (typeof appId !== \"string\" || !appId || /\\s/.test(appId)) return { status: \"invalid-input\" };\n    try {\n      if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n      var sds = SYNO.SDS, map = sds.Config && sds.Config.FnMap, notifier = sds.StatusNotifier;\n      if (typeof sds.AppLaunch !== \"function\" || !map ||\n          !Object.prototype.hasOwnProperty.call(map, appId) || !map[appId] || !notifier ||\n          typeof notifier.isAppEnabled !== \"function\" || !notifier.isAppEnabled(appId) ||\n          typeof notifier.isAppLaunchable !== \"function\" || !notifier.isAppLaunchable(appId)) {\n        return { status: \"unsupported\" };\n      }\n      if (receiverCallback) sds.AppLaunch(appId, config, undefined, receiverCallback);\n      else sds.AppLaunch(appId, config);\n      return { status: \"requested\" };\n    } catch (error) { return { status: \"failed\" }; }\n  }\n  function navigateFileStation(path, isDirectory) {\n    if (disposed) return { status: \"unavailable\" };\n    if (revealRecovery) revealRecovery.cancel();\n    revealRecovery = null;\n    function launchFile(appId, config) {\n      if (isDirectory) return launchApp(appId, config);\n      var recovery = createHostFileRevealRecovery(config.openfile, function () { return !disposed && revealRecovery === recovery; });\n      revealRecovery = recovery;\n      var result = launchApp(appId, config, recovery.receive);\n      if (result.status !== \"requested\") recovery.cancel();\n      return result;\n    }\n    return requestHostFileNavigation(launchFile, path, isDirectory);\n  }\n  function unsupportedOperation() { return { status: disposed ? \"unavailable\" : \"unsupported\" }; }\n  return Object.freeze({\n    platform: function () {\n      if (!disposed) return inspectHostPlatform(ctx);\n      return Object.freeze({\n        web: typeof window !== \"undefined\", host: \"unavailable\",\n        dsmStandalone: null, dsmLanguage: null, appLocale: null,\n        systemVersion: null, fullVersion: null, theme: null\n      });\n    },\n    setTitle: function (title) {\n      if (disposed) return { status: \"unavailable\" };\n      if (typeof title !== \"string\") return { status: \"invalid-input\" };\n      try {\n        var platform = inspectHostPlatform(ctx);\n        if (platform.host === \"dsm\") {\n          if (typeof ctx.appWindow.setTitle !== \"function\") return { status: \"unsupported\" };\n          ctx.appWindow.setTitle(title, undefined, true);\n          return { status: \"ok\", target: \"dsm-window\" };\n        }\n        if (!platform.web) return { status: \"unavailable\" };\n        if (typeof document === \"undefined\") return { status: \"unsupported\" };\n        document.title = title;\n        return { status: \"ok\", target: \"document\" };\n      } catch (error) {\n        return { status: \"failed\" };\n      }\n    },\n    activateWindow: function () {\n      if (disposed) return { status: \"unavailable\" };\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        var win = ctx.appWindow;\n        var activate = typeof win.toFront === \"function\" ? win.toFront : win.activate;\n        if (typeof activate !== \"function\") return { status: \"unsupported\" };\n        // DSM minimizes by hiding; show preserves maximized geometry, unlike restore.\n        if (win.hidden === true || win.minimized === true ||\n            (typeof win.isVisible === \"function\" && win.isVisible() === false)) {\n          if (typeof win.show !== \"function\") return { status: \"unsupported\" };\n          win.show();\n        }\n        activate.call(win);\n        return { status: \"requested\" };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    requestClose: function () {\n      if (disposed) return { status: \"unavailable\" };\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        var win = ctx.appWindow;\n        // DSM returns a short-circuit value; only truthy means standalone main.\n        if (typeof win.close !== \"function\" || typeof win.isStandaloneMainWindow !== \"function\" ||\n            win.isStandaloneMainWindow()) return { status: \"unsupported\" };\n        if (win.canClose === false) return { status: \"blocked\" };\n        win.close();\n        return { status: \"requested\" };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    // DSM's own banner sign-out, for an App that hides the banner (ui.banner: hidden).\n    signOut: function () {\n      if (disposed) return { status: \"unavailable\" };\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        var sds = SYNO.SDS, logout = sds.Utils && sds.Utils.Logout;\n        if (!logout || typeof logout.action !== \"function\") return { status: \"unsupported\" };\n        if (sds.StatusNotifier) sds.StatusNotifier.fireEvent(\"logout\");\n        window.onbeforeunload = sds.onBasicBeforeUnload;\n        logout.action();\n        return { status: \"requested\" };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    openApp: function (appId) { return launchApp(appId, {}); },\n    openURL: function (raw) {\n      if (disposed || typeof window === \"undefined\") return { status: \"unavailable\" };\n      if (typeof raw !== \"string\" || !raw || /[\\s\\x00-\\x1f\\x7f]/.test(raw)) return { status: \"invalid-input\" };\n      if (typeof URL !== \"function\") return { status: \"unsupported\" };\n      var url;\n      try { url = new URL(raw); } catch (error) { return { status: \"invalid-input\" }; }\n      if ((url.protocol !== \"http:\" && url.protocol !== \"https:\") || url.username || url.password) return { status: \"invalid-input\" };\n      if (typeof window.open !== \"function\") return { status: \"unsupported\" };\n      try {\n        var opened = window.open(url.href, \"_blank\", \"noopener,noreferrer\");\n        return { status: \"requested\", windowHandleAvailable: !!opened };\n      } catch (error) { return { status: \"failed\" }; }\n    },\n    openFileManager: function (path) { return navigateFileStation(path, true); },\n    revealFile: function (path) { return navigateFileStation(path, false); },\n    openFile: unsupportedOperation,\n    showFileDetails: unsupportedOperation,\n    openAppSetting: unsupportedOperation,\n    subscribe: function (event, listener) {\n      if (disposed) return { status: \"unavailable\" };\n      if (typeof listener !== \"function\") return { status: \"invalid-input\" };\n      if (event !== \"window-resize\") return { status: \"unsupported\" };\n      var win, callback = listener, active = true;\n      function handler() { if (!disposed && callback) callback(); }\n      function unsubscribe() {\n        if (!active) return;\n        active = false;\n        callback = null;\n        var target = win;\n        win = null;\n        var index = subscriptions.indexOf(unsubscribe);\n        if (index !== -1) subscriptions.splice(index, 1);\n        try { if (target) target.un(\"resize\", handler, target); } catch (error) {}\n      }\n      try {\n        if (inspectHostPlatform(ctx).host !== \"dsm\") return { status: \"unsupported\" };\n        win = ctx.appWindow;\n        if (typeof win.on !== \"function\" || typeof win.un !== \"function\") return { status: \"unsupported\" };\n        subscriptions.push(unsubscribe);\n        win.on(\"resize\", handler, win);\n        if (disposed) return { status: \"unavailable\" };\n        return Object.freeze({ status: \"subscribed\", dispose: unsubscribe });\n      } catch (error) {\n        unsubscribe();\n        return { status: \"failed\" };\n      }\n    },\n    dispose: function () {\n      if (disposed) return;\n      disposed = true;\n      if (revealRecovery) revealRecovery.cancel();\n      revealRecovery = null;\n      subscriptions.slice().forEach(function (unsubscribe) { unsubscribe(); });\n      ctx = null;\n    }\n  });\n}";
 /** A static, per-package factory for independent web shells; no Ext or transport. */
 export declare function renderHostAdapterScript(packageId: string): string;
 export declare function hostScriptName(build: number): string;

package/dist/standalone/host-adapter.js

@@ -95,6 +95,19 @@ function createHostAdapter(ctx) {
         return { status: "requested" };
       } catch (error) { return { status: "failed" }; }
     },
+    // DSM's own banner sign-out, for an App that hides the banner (ui.banner: hidden).
+    signOut: function () {
+      if (disposed) return { status: "unavailable" };
+      try {
+        if (inspectHostPlatform(ctx).host !== "dsm") return { status: "unsupported" };
+        var sds = SYNO.SDS, logout = sds.Utils && sds.Utils.Logout;
+        if (!logout || typeof logout.action !== "function") return { status: "unsupported" };
+        if (sds.StatusNotifier) sds.StatusNotifier.fireEvent("logout");
+        window.onbeforeunload = sds.onBasicBeforeUnload;
+        logout.action();
+        return { status: "requested" };
+      } catch (error) { return { status: "failed" }; }
+    },
     openApp: function (appId) { return launchApp(appId, {}); },
     openURL: function (raw) {
       if (disposed || typeof window === "undefined") return { status: "unavailable" };

package/dist/standalone/host-types.d.ts

@@ -37,6 +37,7 @@ export interface HostAdapter {
     setTitle(title: string): HostTitleResult;
     activateWindow(): HostRequestResult;
     requestClose(): HostRequestResult;
+    signOut(): HostRequestResult;
     openApp(appId: string): HostRequestResult;
     openURL(url: string): HostURLResult;
     openFileManager(path: string): HostFileNavigationResult;

package/dist/standalone/manifest.d.ts

@@ -50,6 +50,7 @@ export interface StandaloneManifest {
         aliases?: string[];
         developedBy?: string;
         commands: Record<string, import("../ctl/descriptor.js").Operation>;
+        external?: import("../ctl/descriptor.js").ApiPayload['external'];
     };
     metadata?: PackageMetadata;
     dependencies?: PackageDependencies;
@@ -78,6 +79,8 @@ export interface StandaloneManifest {
             command: string[];
         };
         window?: WindowSize;
+        /** `ui.banner: hidden`: a standalone page drops DSM's banner (name, account menu), as DSM's own "Hide banner" does for every App. */
+        banner?: "hidden";
     };
     i18n?: StandaloneI18n;
     capabilities: Capabilities;

package/dist/standalone/manifest.js

@@ -495,6 +495,16 @@ function readManifest(raw, c) {
         c.fail("CTL_DECLARATION_INVALID", "ctl requires enabled and explicit commands.");
         return undefined;
     }
+    if (isRecord(raw.ctl) && raw.ctl.external !== undefined) {
+        const external = raw.ctl.external;
+        if (!isRecord(external) || Object.keys(external).length < 1 || Object.keys(external).length > 16 ||
+            Object.entries(external).some(([protocol, entry]) => !/^[a-z][a-z0-9-]{0,63}$/.test(protocol) ||
+                !isRecord(entry) || Object.keys(entry).length !== 1 || typeof entry.method !== 'string' ||
+                entry.method.length > 128 || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(entry.method))) {
+            c.fail('CTL_EXTERNAL_DECLARATION_INVALID', 'ctl.external requires protocol names and fixed RPC methods.');
+            return undefined;
+        }
+    }
     return {
         ...(raw.ctl ? { ctl: raw.ctl } : {}),
         root: c.root,
@@ -870,8 +880,11 @@ function readUi(value, c) {
     if (read && "error" in read)
         return c.fail("STANDALONE_UI_WINDOW_INVALID", read.error);
     const window = read ? { window: read.size } : {};
+    if (value.banner !== undefined && value.banner !== "shown" && value.banner !== "hidden")
+        return c.fail("STANDALONE_UI_BANNER_INVALID", "ui.banner must be shown or hidden.");
+    const banner = value.banner === "hidden" ? { banner: "hidden" } : {};
     if (value.build === undefined) {
-        return dir ? { dir, ...launch, ...window } : undefined;
+        return dir ? { dir, ...launch, ...window, ...banner } : undefined;
     }
     const build = value.build;
     const command = isRecord(build) ? build.command : undefined;
@@ -887,6 +900,7 @@ function readUi(value, c) {
             build: { cwd, command: command },
             ...launch,
             ...window,
+            ...banner,
         }
         : undefined;
 }

package/docs/ctl-external.md

@@ -0,0 +1,212 @@
+# Local external callers for MCP
+
+The CLI supplies a generic local bridge transport:
+
+```text
+synopkgland ctl external --protocol example-external-v1 --host controller --input - --json
+```
+
+It accepts one UTF-8 JSON object from stdin and emits exactly one compact
+`{ok:true,data:...}` or `{ok:false,error:{code,message,hint}}` object on stdout.
+Input and output, including the final newline, are bounded to 1 MiB. Requests
+have a shared 30-second network budget. A bridge should also bound the child
+process lifetime, stdin and stderr. Invalid/duplicate options and duplicate JSON
+keys are refused. Business arguments never belong in argv.
+
+This command is implemented in the CLI. Apps must implement the trusted entry
+below; the CLI does not create an MCP server, HTTP listener, shared service or
+tool Engine. Apps without that entry remain unsupported. No SDK change or
+automatic App upgrade is included.
+
+## App declaration and approval
+
+An App may declare up to 16 lowercase protocol IDs (1–64 letters/digits/dashes,
+starting with a letter). There is no App-specific protocol dispatch. For a native
+App with explicit ordinary ctl commands, extend `dsm-package.yaml`:
+
+```yaml
+ctl:
+  enabled: true
+  # Keep the App's existing aliases, developedBy and commands here.
+  external:
+    example-external-v1:
+      method: bridge.external
+```
+
+The existing route registry must export `bridge.external` as an administrator
+RPC method (or have an administrator-only App entry). Build rejects missing,
+nonadministrator and raw HTTP routes. The generated v1 API descriptor adds:
+
+```json
+{
+  "external": {"example-external-v1": {"method": "bridge.external"}}
+}
+```
+
+This is a field of `payload`, included in its existing canonical SHA-256.
+`payload.bindings["bridge.external"]` is
+`{"effect":"destructive","permission":"administrators"}` as a conservative
+transport classification. The external method cannot appear as a command ID or
+any ordinary command's invoke, job, pagination, streaming or upload helper.
+`ctl list` displays declarations separately from ordinary commands.
+App-owned runtime descriptors may produce this same extension. Keep their
+packaged descriptor, permissions and registry in agreement with the live one.
+
+The operator must first register/sign in locally, then explicitly approve the
+specific App's fresh description with ordinary discovery, for example:
+
+```sh
+synopkgland host login controller
+synopkgland ctl list --host controller --app Example --refresh --approve-installed --json
+```
+
+Approval authorizes sending the DSM session to that installed App's fixed CGI.
+Obtain the user's authorization before approving an App. External calls cannot
+approve Apps or update description pins. They match the protocol against cached
+descriptors of approved installed package versions, then reread and verify the
+selected live descriptor against its approved hash. Zero or multiple matching
+Apps refuse; revoke the unwanted approval or use distinct protocol IDs. A cache
+is only a recipient selector and never grants tool authority.
+
+Only a named, registered host and its OS-stored session are used. Ambient
+`DSM_*` credentials/URL cannot create or replace this login. HTTPS requires the
+stored SHA-256 certificate pin and refuses rotation before sending HTTP headers,
+including under ordinary ctl's permissive TLS default. Registered strict-TLS/CA
+settings still apply. A registered explicit loopback SSH tunnel is also accepted.
+No default-host fallback, multi-host mode, URL/TLS override, `--yes`, `--via` or
+automatic login is available. Reapprove intentional changes outside the bridge.
+
+## Local stdin/stdout contract
+
+Describe input has exactly these fields:
+
+```json
+{"protocol":"example-external-v1","action":"describe"}
+```
+
+Success data is the App's current Catalog, with a revision binding the entire
+tool set:
+
+```json
+{"ok":true,"data":{"revision":"r1","tools":[{"name":"notes__list","description":"notes.list","inputSchema":{"type":"object","additionalProperties":false},"outputSchema":{"type":"object"},"_meta":{"method":"notes.list"}}]}}
+```
+
+Catalog revisions contain 1–128 letters/digits/underscores/dashes. At most 1024
+tools fit within the output budget. Each tool has a unique MCP-compatible `name`
+(1–128 letters/digits/underscores/dashes), unique original dotted method in
+`_meta.method`, and self-contained JSON Schema 2020-12 input/output objects.
+Other App metadata is preserved. Schema references must be local. The App owns
+tool eligibility, effect, schema hashes and revision construction; the bridge
+may additionally compare these against its matching built-in OpSpecs.
+
+Call input has exactly these fields:
+
+```json
+{"protocol":"example-external-v1","action":"call","revision":"r1","method":"notes.list","arguments":{}}
+```
+
+The CLI fetches a fresh Catalog through the trusted entry, refuses stale
+revisions/unknown methods, and validates arguments against that tool's current
+input schema. Success data is the App's tool Result, validated against the
+tool's output schema. The CLI never starts an ordinary ctl flow for this call.
+`actor`, `via`, `allowMutation`, `allow_mutation` and `host` are forbidden as
+request fields and root argument fields. They cannot establish authority through
+nested business data either: App handlers must derive transport authority from
+the verified server context. Model arguments are business data only.
+
+## Trusted App RPC contract
+
+Both actions enter only the declared method at the package's existing fixed
+`/webman/3rdparty/<package>/cgi/api.cgi`, using the stored DSM session and
+SynoToken. This initial implementation requires `dsm-session`; Apps using
+`dsm-app-session` cannot declare external entries in generated descriptions.
+
+The CLI adds installed-package and approved-description pins to RPC `params`:
+
+```json
+{"method":"bridge.external","params":{"protocol":"example-external-v1","action":"call","revision":"r1","method":"notes.list","arguments":{},"package":{"id":"Example","version":"1"},"descriptionSha256":"<approved 64-hex hash>"}}
+```
+
+Describe has the same pins plus `protocol` and `action`, without call fields.
+The App must strictly decode this envelope and, for **both** actions:
+
+1. Authenticate the current DSM session and SynoToken, require a current
+   administrator, and establish the verified user from the SDK Caller.
+2. Verify the protocol, installed package/version and current descriptor hash.
+   Do not echo unverified request values as evidence.
+3. Derive MCP provenance from this dedicated entry. Never take actor, provenance,
+   scope authority or mutation intent from request JSON. Ordinary ctl must keep
+   its existing provenance and must not expose this entry as a normal tool.
+4. Describe the eligible shared Engine tool set. For calls, atomically compare
+   revision and pins with the tool set being dispatched, before any effect.
+   CLI preflight cannot close a server-side revision race.
+5. Resolve scope/targets, enforce explicit server-authorized mutation intent,
+   draft/selection gates and budgets, then execute the shared Engine. Human-only
+   methods must refuse guessed names; sensitive adapters return existing cards.
+
+Use the ordinary SDK `{success,data|error}` RPC envelope. On success, `data` is:
+
+```json
+{
+  "verified": {
+    "protocol": "example-external-v1",
+    "package": {"id": "Example", "version": "1"},
+    "descriptionSha256": "<verified 64-hex hash>",
+    "user": "<verified DSM username>",
+    "administrator": true,
+    "revision": "r1"
+  },
+  "data": {"revision":"r1","tools":[]}
+}
+```
+
+For calls the inner `data` is the tool Result and the verified revision must
+equal the requested revision. The CLI verifies all evidence against its pins,
+stored username and Catalog revision, then unwraps only the inner data for the
+local bridge. Evidence is an assertion by the approved authenticated App, not
+a signed delegation token. The server must perform these checks before dispatch;
+returning evidence afterward cannot undo an unauthorized effect.
+
+## Failure and verification boundary
+
+The CLI rereads local session/host/approval state before each external RPC. It
+does not refresh expired sessions. All errors return bounded generic text;
+upstream messages, request arguments and exception text are never echoed.
+Session carriers and schema-marked sensitive call values are redacted from
+results. The App remains responsible for its own secret-free Catalog and Result.
+Authentication failures exit 2, invalid input/options 3, trust/permission/revision
+refusals 4, contract failures 5 and network failures 6.
+
+There is exactly one mutation dispatch attempt. Timeout, interruption, invalid
+evidence/schema or oversized output may follow a committed mutation; none
+causes a retry. Query the original receipt/Operation or current state before any
+further action. Killing the CLI stops observation and does not cancel an App
+Operation.
+
+Tests exercise compiled CLI subprocesses and a local TLS fixture, including
+fresh administrator checks, revision races, lost replies and certificate
+rotation. They do not establish any App's installed or deployed readiness.
+
+## Syngle I-B / K9 integration checklist
+
+- Keep the existing bridge argv and stdin/stdout shapes, with
+  `syngle-external-v1` declared under `ctl.external`; no protocol-ID rename is
+  needed. Select a fixed administrator RPC method such as `mcp.external`.
+- Register that exact RPC in CGI and worker route composition and digest-bound
+  administrator permissions. Align generated/static and runtime descriptors,
+  their canonical hashes and package version. Keep it out of ordinary ctl flows.
+- Strictly decode the trusted RPC params and implement the evidence envelope
+  above. Generate Describe data with the current exact `mcpbridge.NewCatalog`.
+  Compare revision/pins at the shared Engine dispatch boundary, not after effects.
+- Construct `aitools.NewExternal(Config)` per verified Caller, preserving the
+  scope resolver, mutation-intent gate, selection/DraftGate and read-NAS budgets.
+  Keep `Authority.AllowMutation` server-authorized; do not enable it because the
+  request uses this transport. Return the original `aitools.Result` for Call.
+- After the coordinator releases a compatible CLI, update the distribution pin
+  and setup guidance. Login alone is insufficient: include explicit App
+  discovery/approval. Preserve the bridge's exact OpSpec comparison, cancellation
+  semantics, output budget and refusal to retry lost mutations.
+- Run composed App/bridge acceptance for expired/nonadmin sessions, forged
+  authority, stale/racing revisions, human-only guesses, ordinary `via=ctl`,
+  trusted `via=mcp`, AI disabled and lost mutation replies. Until then, report
+  Syngle end-to-end integration as pending.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.40.0",
+  "version": "0.41.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "assets",
     "CHANGELOG.md",
     "schema",
+    "docs/ctl-external.md",
     "skills"
   ],
   "scripts": {
@@ -27,7 +28,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.35.0",
+    "@synopackageland/templates": "~0.35.1",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/schema/synopkgland-api-v1.schema.json

@@ -397,6 +397,29 @@
               "flow"
             ]
           }
+        },
+        "external": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 16,
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,63}$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "method": {
+                "type": "string",
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+              }
+            },
+            "required": [
+              "method"
+            ]
+          }
         }
       },
       "required": [

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.35.0`. A templates patch needs only a
+The CLI installs templates through `~0.35.1`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.37.0 and CLI 0.40.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.38.0 and CLI 0.41.1 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -41,6 +41,15 @@ cannot upgrade a connection; use an existing upgrade-capable deployment
 transport. The audit follows each configured Go binary's Linux import graph,
 including declared workers; unshipped dev commands are excluded.
 
+SDK/App 0.38.0 allows 300 seconds for requests by default, with the browser
+waiting 302 seconds. Explicit budgets and earlier parent deadlines still win.
+For long work, use existing independent workers with prompt job admission,
+progress and authorized status/result polling by the original ID. A timed-out
+status read does not fail a queued/running job; reuse the same key/input after
+a lost admission reply. Read [reference/create.md](reference/create.md) for
+the deadline and background-job contract. The independent ctl transport keeps
+its 62-second default; use an explicit timeout or an existing nonblocking job.
+
 Use `ipc.StartUnix(ctx, path, handler)` for multiple private data-plane sockets.
 Each direct `.sock` child of the package `var/run` gets an independent handle
 with Close, Shutdown and Wait. Stop/revoke closes active streams and hijacked
@@ -268,6 +277,8 @@ Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK
 `ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
 favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
 
+`ui.banner: hidden` 只替這個 App 的全頁拿掉 DSM 橫幅（預設 `shown` 保留）；適合 App 外框已有名稱與帳號區時，帳號與登出改由 SDK `AppShell` 負責。細節見 reference/ui-vue.md。
+
 Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
 `defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
 不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。

package/skills/reference/create.md

@@ -62,19 +62,19 @@ backend: {runtime: rust, dir: app, entry: hello, methods: [hello.greet]}
 
 ## 請求期限與視窗尺寸
 
-所有 App 的 backend 請求期限預設 60 秒；`backend.timeout_seconds`（1–3600 的整數）改成別的值，go、python、node、rust 都適用。到期時 App 回 `request_timeout`；DSM 視窗把同一值放進 `ctx.requestTimeout`（毫秒），`ctx.call` 與 SDK 的瀏覽器 client 多等 2 秒，讓 backend 的回覆先到。超過期限的工作改用 jobs 或 root job，不要拉長同步請求。
+SDK/App 0.38.0 的 backend 請求期限預設 300 秒，DSM 視窗與 TS client 預設等候 302 秒。CLI 從 App 所選 SDK 的 timeout spec 讀取預設；`backend.timeout_seconds`（1–3600 的整數）可明確覆寫，go、python、node、rust 都適用，較早的 parent deadline 仍優先。到期時 App 回 `request_timeout`；DSM 視窗把工作期限放進 `ctx.requestTimeout`（毫秒），`ctx.call` 與 SDK 瀏覽器 client 多等 2 秒，讓 backend 的回覆先到。已安裝的 App、舊 SDK 或既有明確 timeout 不會自動改變；需使用匹配的 Go/TS SDK 重建。
 
 - python、node、rust：build 把它寫進 `bridge.json` 的 `timeout_seconds`；runtime 以它為期限，傳給 App 的 `deadline_ms` 是送出呼叫時剩下的時間。
-- go：build 以 `-X main.requestTimeout=<秒>` 傳入。要寫 `timeout_seconds`，`main.go` 必須讀這個變數，否則 check 回 `STANDALONE_TIMEOUT_UNSUPPORTED`；main 沒有讀它時，CGI 維持 SDK 的 20 秒：
+- go：build 以 `-X main.requestTimeout=<秒>` 傳入。要寫 `timeout_seconds`，`main.go` 必須讀這個變數，否則 check 回 `STANDALONE_TIMEOUT_UNSUPPORTED`；未設定時使用所選 SDK 的 `api.DefaultRequestTimeout`：
 
 ```go
-// Set by synopkgland build through -ldflags -X: backend.timeout_seconds, 60 unless set.
+// Set by synopkgland build through -ldflags -X: backend.timeout_seconds.
 var requestTimeout = ""
 
 func deadline() api.DeadlineOption {
 	seconds, err := strconv.Atoi(requestTimeout)
 	if err != nil || seconds <= 0 {
-		seconds = 60
+		return api.Timeout(api.DefaultRequestTimeout)
 	}
 	return api.Timeout(time.Duration(seconds) * time.Second)
 }
@@ -84,6 +84,17 @@ func deadline() api.DeadlineOption {
 
 - binary：預先建置的 CGI 自己決定期限，不接受 `timeout_seconds`；視窗仍等 62 秒。
 
+長時間 NAS 工作沿用既有 jobs 與獨立 worker：
+
+1. 驗證固定 operation 與可信 owner，以 `NewRequestStore` / `SubmitSingleton` 或 `Submit` admission，立即回覆既有 outcome 與原 job ID。
+2. 在套件帳號的獨立 worker 或 resident daemon 執行 `Runner.Work`，用 `Task.Report` 回報 phase/progress；未知總量保持 unknown。SDK 預設 job 與 delegated download 期限為 30 分鐘，可由可信組裝設定有限期限。
+3. 每次 status/result/cancel 都重新驗證權限，以原 ID 有界退避輪詢。`queued` / `running` 顯示仍在工作；慢 NAS 或 status read timeout 只代表狀態暫時無法取得，保留最後狀態，不判定 job 失敗。
+4. admission 回覆遺失時，沿用相同 idempotency key 與 input，或查詢已知 ID；不可因逾時用新 key 重送已派送 mutation。只有 terminal state 能決定完成；取消無法撤回已發生的遠端效果。
+
+直接 File Station 瀏覽器讀取預設也為 302 秒；identity gateway 等候 upstream headers 預設 310 秒，自訂期限需對齊 gateway 與外部 proxy。這些預設不保證所有 DSM/proxy 都能完成五分鐘請求。executor batch 的 60 秒上限、已核准 root policy/program budget 與 credential lifetime 維持原契約；長 root 工作使用既有 `root.start` / `root.jobs.*`。
+
+獨立 `ctl` transport 預設仍是 62 秒。長同步呼叫須明確指定 `--timeout`，或使用既有 nonblocking job flow；參考 [ctl](ctl.md)。完整契約見 SDK 的 [request deadlines](https://github.com/synopackageland/syno-pkg-land-sdk/blob/v0.38.0/docs/request-deadlines.md)。
+
 DSM 視窗預設 960×640、最小 700×420；`ui.window` 只寫要改的欄位：
 
 ```yaml

package/skills/reference/ctl.md

@@ -16,6 +16,27 @@ Use `host show nas` to inspect approvals/pins, `host revoke nas PackageID` to re
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.
 
+## Local MCP external callers
+
+`synopkgland ctl external --protocol <declared-id> --host <profile> --input - --json`
+accepts one strict JSON `describe` or revision-bound `call` on stdin and emits one
+`{ok,data|error}` object. This requires an App-declared `ctl.external` protocol,
+an approved package/version/description pin from ordinary discovery, and a stored
+local login. The CLI rereads the installed inventory and descriptor and verifies
+the App's fresh administrator evidence. HTTPS uses the registered certificate
+pin even when ordinary NAS commands accept certificate changes. Environment
+passwords never log in this caller; model input cannot choose the host, actor,
+provenance or mutation authority. No `--yes`, multi-host selection, credential,
+URL or TLS override is accepted. A lost mutation reply is never retried; query
+the original operation/state first.
+
+Read [the App contract](../../docs/ctl-external.md) before implementing an adapter.
+The trusted App entry must atomically verify revision/pins, authenticate the
+administrator and derive `via=mcp` and mutation authority server-side. Ordinary
+ctl cannot invoke this entry through command flows. A protocol declaration alone
+does not implement these checks or make an App MCP-ready. `syngle-external-v1`
+works as a declared protocol; the CLI has no App-specific protocol branch.
+
 ## Plan command coverage
 
 For packaging an upstream open-source App (including forks with `synology/`),
@@ -111,6 +132,13 @@ every App supports cancellation or singleton deduplication.
 
 For AI consumers:
 
+The independent ctl transport defaults to 62 seconds even with SDK/App 0.38.0.
+For a long synchronous call, set `--timeout` explicitly; for an existing job
+flow, use `--no-wait` and the original ID. A status read timeout leaves the last
+known queued/running state intact. If the App's admission API supports an
+idempotency key, reuse the same key and input after a lost reply; never invent
+that support or issue a new mutation key to work around a timeout.
+
 1. Discover the real command schema and current jobs if listing is supported.
    Dry-run mutations, obtain authorization, then submit once with `--yes` and
    `--no-wait` when using a job flow. Keep host, App and original operation ID.

package/skills/reference/ui-vue.md

@@ -177,6 +177,23 @@ Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK
 `ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
 favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
 
+`ui.banner: shown | hidden` 決定 App 全頁（standalone）上方要不要有 DSM 橫幅
+（App 名稱與帳號選單）。預設 `shown`，維持 DSM 原本的樣子；`hidden` 只替這個 App
+拿掉橫幅，用的是 DSM 全域「隱藏橫幅」同一個 class，不改 DSM 設定，DSM 桌面視窗也照樣有標題列。
+
+什麼時候藏：App 自己的外框已經有 App 名稱與帳號區，例如用 SDK `AppShell` 的全頁 web App，
+再疊一條 DSM 橫幅只是重複。藏掉後帳號與登出由 SDK 外框負責：`AppShell` 偵測到 DSM 沒畫帳號，
+就在側欄底部顯示登入者與「登出」按鈕，登出呼叫 `ctx.host.signOut()`（照 DSM 橫幅選單的登出流程，
+DSM 以外回 `unsupported`）。自己寫 `sidebar-footer` 的 App 要自己放登出，呼叫同一個方法。
+App 沒有自己的帳號區時就保留橫幅，否則使用者會找不到登出。其他值 check 回 `STANDALONE_UI_BANNER_INVALID`。
+
+```yaml
+ui:
+  dir: ui/dist
+  launch: new-page
+  banner: hidden
+```
+
 Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
 `defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
 不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。