evolcore 0.0.26 → 0.0.28

package/dist/core/command/agent-storage-menu.js

@@ -0,0 +1,443 @@
+import crypto from 'node:crypto';
+import { isValidAid } from '../../aun/aid/validation.js';
+import { isExplicitGroupId } from '../../aun/group/index.js';
+import { listStaticAgentOwners } from '../../config/peer-role-resolver.js';
+import { authorizeOperation } from '../auth/auth-gateway.js';
+import { auditCommandAuthorization } from '../auth/authorization-audit.js';
+import { DataRootError } from './data-root-resolver.js';
+const ROOT_TTL_MS = 10 * 60_000;
+const OPERATIONS = {
+    root: 'file.root.storage', list: 'file.storage.list', query: 'file.storage.query',
+    fetch: 'file.storage.fetch', quota: 'file.storage.quota',
+};
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function fail(code, message) { throw new DataRootError(code, message); }
+function numeric(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function timestamp(value) {
+    const n = numeric(value);
+    return n === null ? null : n < 10_000_000_000 ? n * 1000 : n;
+}
+function textValue(value) { return typeof value === 'string' && value ? value : null; }
+function nodeType(node) {
+    // Fail closed if an upstream compatibility view calls a linked node a file.
+    for (const type of [node.type, node.node_type]) {
+        if (type === 'symlink' || type === 'mount')
+            return type;
+    }
+    const type = node.type ?? node.node_type;
+    if (type === 'dir' || type === 'folder' || type === 'directory')
+        return 'dir';
+    if (type === 'file' || type === 'object')
+        return 'file';
+    return type === 'symlink' || type === 'mount' ? type : 'unknown';
+}
+function command(request) {
+    return typeof request.cmd === 'string' && request.cmd.trim()
+        ? request.cmd.trim().split(/\s+/)[0] : `/${request.name ?? ''}`;
+}
+export function isAgentStorageMenuRequest(request) {
+    const cmd = command(request);
+    return cmd === '/agent-storage-root' || cmd === '/storage'
+        || (cmd === '/file' && typeof record(request.args).rootId === 'string'
+            && record(request.args).rootId.startsWith('sr1.'));
+}
+export function normalizeStorageRelativePath(value) {
+    if (typeof value !== 'string' || !value.trim() || value.length > 4096) {
+        return fail('INVALID_ROOT_PATH', 'A root-relative storage path is required');
+    }
+    const raw = value.trim();
+    // Do not let the SDK normalize traversal, Windows paths or encoded separators away.
+    if (/^[\/]/.test(raw) || /[\\:\0%]/.test(raw) || raw.split('/').includes('..')) {
+        return fail('INVALID_ROOT_PATH', 'Storage paths must be relative and cannot contain traversal or an AID');
+    }
+    const segments = raw.split('/').filter(part => part && part !== '.');
+    if (segments.length > 64)
+        return fail('INVALID_ROOT_PATH', 'Storage path is too deep');
+    return segments.join('/') || '.';
+}
+export class AgentStorageMenuService {
+    secret;
+    now;
+    ttlMs;
+    rpcTimeoutMs;
+    isOwner;
+    authorize;
+    inflight = new Map();
+    constructor(options = {}) {
+        this.secret = options.secret ?? crypto.randomBytes(32);
+        this.now = options.now ?? Date.now;
+        this.ttlMs = options.ttlMs ?? ROOT_TTL_MS;
+        this.rpcTimeoutMs = options.rpcTimeoutMs ?? 15_000;
+        this.isOwner = options.isOwner ?? ((aid, principalId) => listStaticAgentOwners(aid, { fresh: true }).includes(principalId));
+        this.authorize = options.authorize ?? authorizeOperation;
+    }
+    /** Also run before Menu deduplication, so replay cannot bypass revocation/expiry. */
+    preflight(request, subject, audit = true) {
+        let operation = 'file.root.storage';
+        try {
+            const cmd = command(request);
+            const args = record(request.args);
+            const method = cmd === '/agent-storage-root' && request.type === 'menu.query' ? 'root'
+                : cmd === '/storage' && request.type === 'menu.query' && args.view === 'quota' ? 'quota'
+                    : cmd === '/file' && request.type === 'menu.query' ? 'query'
+                        : cmd === '/file' && request.type === 'menu.action' && (request.action === 'list' || request.action === 'fetch')
+                            ? request.action : fail('NOT_SUPPORTED', 'Unsupported Agent storage operation');
+            operation = OPERATIONS[method];
+            const targetAid = subject.selfAid ?? '';
+            if (subject.fromControlChannel || subject.channelType !== 'aun' || subject.chatType !== 'private') {
+                fail('NOT_SUPPORTED', 'Use the target Agent AUN private channel for storage');
+            }
+            if (!subject.menuEncrypted)
+                fail('MENU_TOKEN_ENCRYPTION_REQUIRED', 'Agent storage Menu requests require E2EE');
+            if (!isValidAid(targetAid) || isExplicitGroupId(targetAid)
+                || !isValidAid(subject.principalId ?? '') || isExplicitGroupId(subject.principalId ?? '')
+                || subject.role !== 'owner' || !this.isOwner(targetAid, subject.principalId)) {
+                fail('ROOT_FORBIDDEN', 'Agent cloud storage requires the static Agent owner');
+            }
+            const allowedKeys = method === 'root' ? [] : method === 'quota' ? ['rootId', 'view']
+                : method === 'list' ? ['rootId', 'path', 'cursor', 'limit', 'includeHidden', 'offset'] : ['rootId', 'path'];
+            if (request.agent !== undefined
+                || (request.args !== undefined && (!request.args || Array.isArray(request.args) || typeof request.args !== 'object'))
+                || Object.keys(args).some(key => !allowedKeys.includes(key))) {
+                fail('INVALID_ARGUMENT', 'Unsupported Agent storage arguments');
+            }
+            const root = method === 'root' ? undefined : this.resolveRoot(args.rootId, subject);
+            if (method === 'list' || method === 'query' || method === 'fetch') {
+                const path = normalizeStorageRelativePath(args.path ?? (method === 'list' ? '.' : undefined));
+                if (method === 'list')
+                    this.listOptions(args, path);
+            }
+            const decision = this.authorize({
+                source: 'menu', subject, audit: false,
+                intent: { operation, scope: 'agent', source: 'menu', args: { self: targetAid } },
+            });
+            if (!decision.allow)
+                fail('PERMISSION_DENIED', 'Agent storage operation is not allowed by the current policy');
+            if (audit)
+                this.audit(subject, operation, 'allow', 'authorized');
+            return { method, operation, args, targetAid, root };
+        }
+        catch (error) {
+            if (audit)
+                this.audit(subject, operation, 'deny', 'blocked', error);
+            throw error;
+        }
+    }
+    async execute(request, subject, resolveClient) {
+        const authorized = this.preflight(request, subject);
+        let relativePath;
+        try {
+            const client = resolveClient?.(subject.channel, authorized.targetAid);
+            if (!client || client.aid !== authorized.targetAid)
+                fail('TEMPORARILY_UNAVAILABLE', 'Target Agent storage connection is unavailable');
+            const { method, args, targetAid, root } = authorized;
+            let data;
+            if (method === 'root' || method === 'quota') {
+                const quota = await this.quota(client, targetAid);
+                if (method === 'quota')
+                    data = { root: this.summary(root), backend: 'aun-storage', ...quota };
+                else {
+                    const claims = {
+                        v: 1, kind: 'agent-storage', targetAid, principalId: subject.principalId,
+                        storageOwnerAid: targetAid, bucket: 'default', expiresAt: this.now() + this.ttlMs,
+                        nonce: crypto.randomBytes(12).toString('base64url'),
+                    };
+                    data = {
+                        ...this.summary(claims), rootId: this.sign('sr1', claims), backend: 'aun-storage',
+                        storageOwnerAid: targetAid, bucket: 'default', virtualPath: `${targetAid}:/`, readOnly: true,
+                        capabilities: { list: true, query: true, fetch: true, quota: true }, quota,
+                    };
+                }
+            }
+            else {
+                relativePath = normalizeStorageRelativePath(args.path ?? (method === 'list' ? '.' : undefined));
+                const node = await this.nativePath(client, targetAid, relativePath);
+                if (method === 'list') {
+                    if (nodeType(node) !== 'dir')
+                        fail('NOT_A_DIRECTORY', 'Storage path is not a directory');
+                    data = await this.list(client, root, relativePath, args);
+                }
+                else if (method === 'query') {
+                    if (nodeType(node) === 'file') {
+                        const head = await this.rpc(client, targetAid, 'storage.head_object', { object_key: relativePath });
+                        this.assertOwnedNode(head, targetAid);
+                        data = this.metadata({ ...head, type: 'file' }, relativePath);
+                    }
+                    else
+                        data = this.metadata(node, relativePath);
+                }
+                else {
+                    if (nodeType(node) !== 'file')
+                        fail('NOT_SUPPORTED', 'Only ordinary storage files can be downloaded');
+                    data = await this.fetch(client, root, relativePath);
+                }
+                data = { ...data, backend: 'aun-storage', root: this.summary(root) };
+            }
+            // An owner or root can be revoked while an RPC is in flight.
+            this.preflight(request, subject, false);
+            this.audit(subject, authorized.operation, 'allow', 'completed', undefined, relativePath);
+            return data;
+        }
+        catch (error) {
+            this.audit(subject, authorized.operation, 'allow', 'failed', error, relativePath);
+            throw error;
+        }
+    }
+    resolveRoot(value, subject) {
+        if (value === undefined)
+            fail('MISSING_ROOT_ID', 'A storage rootId is required');
+        const claims = this.verify('sr1', value, 'INVALID_ROOT_ID');
+        if (claims.v !== 1 || claims.kind !== 'agent-storage' || claims.bucket !== 'default'
+            || typeof claims.targetAid !== 'string' || claims.targetAid !== claims.storageOwnerAid
+            || typeof claims.principalId !== 'string' || !Number.isFinite(claims.expiresAt)) {
+            return fail('INVALID_ROOT_ID', 'Invalid storage root claims');
+        }
+        if (claims.targetAid !== subject.selfAid)
+            fail('ROOT_SCOPE_MISMATCH', 'Storage root belongs to another Agent');
+        if (claims.principalId !== subject.principalId)
+            fail('ROOT_FORBIDDEN', 'Storage root belongs to another principal');
+        if (claims.expiresAt <= this.now())
+            fail('ROOT_EXPIRED', 'Storage root expired; query the root again');
+        return claims;
+    }
+    sign(prefix, value) {
+        const payload = Buffer.from(JSON.stringify(value)).toString('base64url');
+        const signature = crypto.createHmac('sha256', this.secret).update(`${prefix}.${payload}`).digest('base64url');
+        return `${prefix}.${payload}.${signature}`;
+    }
+    verify(prefix, value, code) {
+        if (typeof value !== 'string' || value.length > 16_384)
+            return fail(code, 'Invalid storage credential');
+        const parts = value.split('.');
+        if (parts.length !== 3 || parts[0] !== prefix || !/^[\w-]+$/.test(parts[2]))
+            return fail(code, 'Invalid storage credential');
+        const expected = crypto.createHmac('sha256', this.secret).update(`${prefix}.${parts[1]}`).digest();
+        const actual = Buffer.from(parts[2], 'base64url');
+        if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected))
+            return fail(code, 'Invalid storage credential signature');
+        try {
+            const parsed = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error();
+            return parsed;
+        }
+        catch {
+            return fail(code, 'Invalid storage credential payload');
+        }
+    }
+    summary(root) {
+        return { scope: 'agent-storage', targetAid: root.targetAid, expiresAt: root.expiresAt };
+    }
+    async quota(client, targetAid) {
+        const raw = await this.rpc(client, targetAid, 'storage.get_quota', {});
+        this.assertOwnedNode(raw, targetAid);
+        const usedBytes = numeric(raw.used_bytes ?? raw.quota_used_bytes);
+        const quotaBytes = numeric(raw.quota_bytes ?? raw.quota_total_bytes);
+        return {
+            quotaBytes: quotaBytes === 0 ? null : quotaBytes, usedBytes,
+            availableBytes: quotaBytes && usedBytes !== null ? Math.max(0, quotaBytes - usedBytes) : null,
+            objectCount: numeric(raw.object_count),
+        };
+    }
+    assertOwnedNode(raw, targetAid) {
+        const owner = raw.owner_aid ?? raw.owner ?? raw.owner_principal;
+        if ((typeof owner === 'string' && owner !== targetAid) || (raw.bucket !== undefined && raw.bucket !== 'default')) {
+            fail('ROOT_SCOPE_MISMATCH', 'Storage node is outside the Agent storage root');
+        }
+    }
+    async nativePath(client, targetAid, relativePath) {
+        // lstat does not follow the final link. Check every prefix, not only the leaf.
+        const parts = relativePath === '.' ? [] : relativePath.split('/');
+        let node = {};
+        for (let index = 0; index <= parts.length; index++) {
+            const raw = await this.rpc(client, targetAid, 'storage.fs.lstat', { path: parts.slice(0, index).join('/') });
+            node = record(raw.node ?? raw);
+            this.assertOwnedNode(node, targetAid);
+            const type = nodeType(node);
+            if (type === 'mount' || type === 'symlink' || type === 'unknown') {
+                fail('NOT_SUPPORTED', 'Storage links and mounts are display-only');
+            }
+            if (index < parts.length && type !== 'dir')
+                fail('NOT_A_DIRECTORY', 'Storage ancestor is not a directory');
+        }
+        return node;
+    }
+    metadata(node, relativePath) {
+        const type = nodeType(node);
+        return {
+            path: relativePath, type: type === 'dir' ? 'directory' : type, nodeType: type,
+            navigable: type === 'dir', fetchable: type === 'file',
+            size: type === 'file' ? numeric(node.size ?? node.size_bytes) : null,
+            mtime: timestamp(node.mtime ?? node.updated_at),
+            contentType: textValue(node.content_type), sha256: textValue(node.sha256),
+            etag: textValue(node.etag), version: numeric(node.version),
+            isPublic: typeof node.is_private === 'boolean' ? !node.is_private : null,
+        };
+    }
+    listOptions(args, relativePath) {
+        const limit = args.limit ?? 100;
+        if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 200
+            || (args.offset !== undefined && args.offset !== 0)
+            || (args.includeHidden !== undefined && typeof args.includeHidden !== 'boolean')) {
+            return fail('INVALID_ARGUMENT', 'Storage list requires limit 1..200, offset 0 and a boolean includeHidden');
+        }
+        const includeHidden = args.includeHidden === true;
+        const rootHash = crypto.createHash('sha256').update(String(args.rootId)).digest('hex');
+        let page = 1;
+        let marker;
+        if (args.cursor !== undefined && args.cursor !== null) {
+            const cursor = this.verify('sc1', args.cursor, 'INVALID_ARGUMENT');
+            if (cursor.rootHash !== rootHash || cursor.path !== relativePath || cursor.limit !== limit
+                || cursor.includeHidden !== includeHidden || !Number.isSafeInteger(cursor.page) || cursor.page < 1
+                || (cursor.marker !== undefined && typeof cursor.marker !== 'string')) {
+                fail('INVALID_ARGUMENT', 'Storage cursor does not match this directory request');
+            }
+            ({ page, marker } = cursor);
+        }
+        return { rootHash, path: relativePath, limit, includeHidden, page, marker };
+    }
+    async list(client, root, relativePath, args) {
+        const { rootHash, limit, includeHidden, page, marker } = this.listOptions(args, relativePath);
+        const raw = await this.rpc(client, root.targetAid, 'storage.fs.list', {
+            path: relativePath === '.' ? '' : relativePath, page, size: limit, ...(marker ? { marker } : {}),
+        });
+        this.assertOwnedNode(raw, root.targetAid);
+        const items = raw.nodes ?? raw.items;
+        if (!Array.isArray(items))
+            fail('INVALID_RESPONSE', 'Storage list did not return nodes');
+        const entries = items.map(value => {
+            const node = record(value);
+            const name = textValue(node.name);
+            if (!name || name === '.' || name === '..' || /[\/\\:\0%]/.test(name)) {
+                return fail('INVALID_RESPONSE', 'Storage list returned an invalid entry name');
+            }
+            // Links/mounts may describe a foreign source; return only their local name and type.
+            const type = nodeType(node);
+            const native = type === 'dir' || type === 'file';
+            if (native)
+                this.assertOwnedNode(node, root.targetAid);
+            const entryPath = relativePath === '.' ? name : `${relativePath}/${name}`;
+            return { name, ...this.metadata(native ? node : { type }, entryPath) };
+        }).filter(entry => includeHidden || !entry.name.startsWith('.'));
+        const nextMarker = textValue(raw.next_marker);
+        const total = numeric(raw.total);
+        const size = numeric(raw.size) || limit;
+        const markerAbsent = raw.next_marker === undefined || raw.next_marker === null;
+        if ((raw.next_marker != null && typeof raw.next_marker !== 'string')
+            || (nextMarker && nextMarker.length > 8000)
+            || (raw.total != null && (total === null || !Number.isSafeInteger(total)))
+            || (raw.size != null && (!Number.isSafeInteger(raw.size) || Number(raw.size) < 1 || Number(raw.size) > limit))
+            || (raw.page != null && raw.page !== page)
+            || items.length > size) {
+            fail('INVALID_RESPONSE', 'Storage returned invalid pagination metadata');
+        }
+        const hasMore = !!nextMarker || (markerAbsent && total !== null && page * size < total);
+        if (nextMarker && nextMarker === marker)
+            fail('INVALID_RESPONSE', 'Storage returned a non-advancing cursor');
+        if (markerAbsent && total === null && items.length >= size) {
+            fail('INVALID_RESPONSE', 'Storage omitted pagination metadata');
+        }
+        return {
+            path: relativePath, entries, limit, total: includeHidden ? total : null, hasMore,
+            nextCursor: hasMore ? this.sign('sc1', {
+                rootHash, path: relativePath, limit, includeHidden, page: page + 1,
+                ...(nextMarker ? { marker: nextMarker } : {}),
+            }) : null,
+        };
+    }
+    async fetch(client, root, relativePath) {
+        // Head and ticket address native objects in this owner's bucket, not another VFS owner.
+        const head = await this.rpc(client, root.targetAid, 'storage.head_object', { object_key: relativePath });
+        this.assertOwnedNode(head, root.targetAid);
+        const requestedAt = this.now();
+        const remaining = Math.floor((root.expiresAt - requestedAt) / 1000);
+        if (remaining < 1)
+            fail('ROOT_EXPIRED', 'Storage root expired; query the root again');
+        const ttl = Math.min(60, remaining);
+        const ticket = await this.rpc(client, root.targetAid, 'storage.create_download_ticket', {
+            object_key: relativePath, expire_in_seconds: ttl,
+        });
+        this.assertOwnedNode(ticket, root.targetAid);
+        const urlValue = textValue(ticket.url ?? ticket.download_url);
+        let url;
+        try {
+            url = new URL(urlValue ?? '');
+        }
+        catch {
+            return fail('INVALID_RESPONSE', 'Storage did not return a valid download URL');
+        }
+        if (url.protocol !== 'https:' || url.username || url.password)
+            fail('INVALID_RESPONSE', 'Storage download requires HTTPS');
+        const isPublic = head.is_private === false && !url.searchParams.has('t');
+        const expiresAt = isPublic ? null : timestamp(ticket.expire_at);
+        if (!isPublic && (!url.searchParams.get('t') || expiresAt === null || expiresAt <= this.now()
+            || expiresAt > root.expiresAt || expiresAt > requestedAt + ttl * 1000 + 1000)) {
+            fail('DEPENDENCY_UNAVAILABLE', 'Storage did not issue a valid short-lived private download ticket');
+        }
+        return {
+            ...this.metadata({ ...head, ...ticket, type: 'file' }, relativePath),
+            isPublic,
+            download: { mode: 'url', method: 'GET', url: urlValue, expiresAt },
+        };
+    }
+    async rpc(client, targetAid, method, args) {
+        if ((this.inflight.get(targetAid) ?? 0) >= 4)
+            fail('RATE_LIMITED', 'Too many Agent storage requests');
+        this.inflight.set(targetAid, (this.inflight.get(targetAid) ?? 0) + 1);
+        let timer;
+        const pending = Promise.resolve().then(() => client.call(method, {
+            ...args, owner_aid: targetAid,
+            // get_quota is AID-wide and has no bucket parameter in the RPC contract.
+            ...(method === 'storage.get_quota' ? {} : { bucket: 'default' }),
+        }))
+            .finally(() => {
+            const count = (this.inflight.get(targetAid) ?? 1) - 1;
+            if (count)
+                this.inflight.set(targetAid, count);
+            else
+                this.inflight.delete(targetAid);
+        });
+        try {
+            const value = await Promise.race([pending, new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new DataRootError('EXECUTION_TIMEOUT', 'Agent storage request timed out')), this.rpcTimeoutMs);
+                })]);
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                fail('INVALID_RESPONSE', 'Storage returned an invalid response');
+            return value;
+        }
+        catch (error) {
+            if (error instanceof DataRootError)
+                throw error;
+            const raw = record(error);
+            const codes = {
+                ENOENT: 'NOT_FOUND', '-32008': 'NOT_FOUND', '404': 'NOT_FOUND', '4040': 'NOT_FOUND',
+                EACCES: 'PERMISSION_DENIED', '-32004': 'PERMISSION_DENIED', '403': 'PERMISSION_DENIED', '4030': 'PERMISSION_DENIED',
+                ENOTDIR: 'NOT_A_DIRECTORY', EISDIR: 'NOT_SUPPORTED', ELOOP: 'NOT_SUPPORTED', EDANGLING: 'NOT_SUPPORTED',
+                ECONFLICT: 'CONFLICT', '-32009': 'CONFLICT', ETIMEDOUT: 'EXECUTION_TIMEOUT', TIMEOUT: 'EXECUTION_TIMEOUT',
+                '-32601': 'NOT_SUPPORTED', '-32602': 'INVALID_ARGUMENT',
+            };
+            // Never forward upstream URLs, tokens or server internals in exception messages.
+            return fail(codes[String(raw.code)] ?? 'TEMPORARILY_UNAVAILABLE', 'Agent storage request failed');
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    audit(subject, operation, decision, executionState, error, relativePath) {
+        auditCommandAuthorization({
+            ts: this.now(), source: 'menu', scope: 'agent', dangerous: false, operation, decision, executionState,
+            eventPhase: executionState === 'authorized' || executionState === 'blocked' ? 'preflight' : 'final',
+            executed: executionState === 'completed', actorId: subject.principalId, selfAid: subject.selfAid,
+            agentAid: subject.selfAid, requestId: subject.requestId, sessionId: subject.sessionId,
+            channel: subject.channel, channelId: subject.channelId, role: subject.role,
+            errorCode: error instanceof DataRootError ? error.code : error ? 'INTERNAL_ERROR' : undefined,
+            ...(relativePath ? { argsSummary: { path: relativePath } } : {}),
+        });
+    }
+}
+export const agentStorageMenuService = new AgentStorageMenuService();

package/dist/core/command/cli-intent-parser.js

@@ -1,3 +1,4 @@
+import { parseAgentWelcomeArgs, parseInitializationArgs } from '../../cli/agent-create.js';
 import { normalizeCliArgv } from '../../cli/cli-argv.js';
 import { resolveConfigCommand, } from '../../config/resolved-config-op.js';
 export { normalizeCliArgv, parseLegacyCliCommand, validateCliArgv } from '../../cli/cli-argv.js';
@@ -156,6 +157,15 @@ function parseStatsCommand(argv, source) {
 }
 function parseAgentCommand(argv, source) {
     const subcmd = argv[1];
+    if ((subcmd === 'new' && argv.includes('--initialize')) || subcmd === 'initialize') {
+        try {
+            const parsed = parseInitializationArgs(argv.slice(1));
+            return recognized('agent.initialize', 'control', source, { aid: parsed.aid }, argv, true);
+        }
+        catch {
+            return raw(source, argv, 'Invalid initialization arguments');
+        }
+    }
     if (subcmd === 'persona') {
         const tail = argv.at(-2) === '--format' && argv.at(-1) === 'json' ? argv.slice(0, -2) : argv;
         const isShow = tail.length === 3 && tail[2] === 'show';
@@ -164,6 +174,15 @@ function parseAgentCommand(argv, source) {
             ? recognized('agent.persona', 'agent', source, {}, argv)
             : raw(source, argv, 'Invalid agent persona command');
     }
+    if (subcmd === 'welcome') {
+        try {
+            const { action } = parseAgentWelcomeArgs(argv.slice(2));
+            return recognized('agent.welcome', 'agent', source, { action }, argv);
+        }
+        catch {
+            return raw(source, argv, 'Invalid agent welcome command');
+        }
+    }
     const parsed = parseArgs(argv.slice(2));
     const args = parsed.args;
     if (parsed.positionals.length > 0)