evolcore 0.0.24 → 0.0.25

package/dist/agents/claude-runner.js

@@ -2489,7 +2489,10 @@ export class AgentRunner {
                 const bootstrapWritePaths = modelOverride?.bootstrapAgentMdPath
                     ? [path.resolve(modelOverride.bootstrapAgentMdPath)]
                     : [];
-                const allowedWritePaths = [...new Set([...runtimeWritePaths, ...bootstrapWritePaths])];
+                const personalWritePaths = modelOverride?.personalMdPath
+                    ? [path.resolve(modelOverride.personalMdPath)]
+                    : [];
+                const allowedWritePaths = [...new Set([...runtimeWritePaths, ...bootstrapWritePaths, ...personalWritePaths])];
                 await assertClaudeSettingSourcesHaveLiteralSandboxPaths(projectPath, [...settingSources], managedSettings);
                 const sandboxProjectionDurationMs = Date.now() - sandboxProjectionStartedAt;
                 if (sandboxProjectionDurationMs > 2_000) {

package/dist/agents/codex-runner.js

@@ -1298,7 +1298,7 @@ export class CodexRunner {
         }
         return Object.fromEntries([...paths].map(candidate => [candidate, 'write']));
     }
-    buildPermissionProfileConfig(sessionId, mode, projectPath, bootstrapAgentMdPath) {
+    buildPermissionProfileConfig(sessionId, mode, projectPath, bootstrapAgentMdPath, personalMdPath) {
         const profileName = this.permissionProfileName(sessionId);
         const managedTempDir = this.ensureSessionTempDir(sessionId);
         const network = {
@@ -1324,6 +1324,9 @@ export class CodexRunner {
                         ...(bootstrapAgentMdPath ? {
                             [path.resolve(bootstrapAgentMdPath)]: mode === 'readonly' ? 'read' : 'write',
                         } : {}),
+                        ...(personalMdPath ? {
+                            [path.resolve(personalMdPath)]: mode === 'readonly' ? 'read' : 'write',
+                        } : {}),
                         ...(mode !== 'readonly' && managedTempDir ? {
                             [managedTempDir]: 'write',
                             [managedTempDir + '/**']: 'write',
@@ -1336,12 +1339,12 @@ export class CodexRunner {
             },
         };
     }
-    buildExecutionSandboxOptions(sessionId, mode, projectPath, bootstrapAgentMdPath) {
+    buildExecutionSandboxOptions(sessionId, mode, projectPath, bootstrapAgentMdPath, personalMdPath) {
         const decision = resolvePhaseOneExecutionSandbox(mode, this.permissionContexts.get(sessionId)?.role);
         return {
             decision,
             permissionProfileConfig: decision.state === 'active'
-                ? this.buildPermissionProfileConfig(sessionId, decision.permissionMode, projectPath, bootstrapAgentMdPath)
+                ? this.buildPermissionProfileConfig(sessionId, decision.permissionMode, projectPath, bootstrapAgentMdPath, personalMdPath)
                 : undefined,
             sandbox: decision.state === 'off' ? 'danger-full-access' : undefined,
         };
@@ -1758,7 +1761,7 @@ export class CodexRunner {
         }
         this.chatModes.set(sessionId, callMode);
         const callApprovalPolicy = this.toApprovalPolicy(callMode);
-        const executionSandbox = this.buildExecutionSandboxOptions(sessionId, callMode, projectPath, modelOverride?.bootstrapAgentMdPath);
+        const executionSandbox = this.buildExecutionSandboxOptions(sessionId, callMode, projectPath, modelOverride?.bootstrapAgentMdPath, modelOverride?.personalMdPath);
         const appServer = this.getAppServerClient(callMode === 'fullaccess');
         this.dropExpiredPendingInterrupt(sessionId);
         const effectiveApprovalPolicy = callApprovalPolicy;

package/dist/agents/ecagent-runner.js

@@ -18,8 +18,8 @@ import { appendRequestPath } from './request-identity.js';
 import { getManagedTaskTempDir } from '../cli/task-context.js';
 import { hasTrustedFullAccessContext } from './runner-types.js';
 const PROVIDER_ID = 'evolcore-gateway';
-const DEFAULT_SYSTEM_PROMPT = `You are ecagent, the coding agent built into EvolCore.
-Work directly in the current project. Inspect relevant files before changing them, keep edits scoped, and verify the result.
+const DEFAULT_SYSTEM_PROMPT = `You are ecagent, the coding agent built into EvolCore.
+Work directly in the current project. Inspect relevant files before changing them, keep edits scoped, and verify the result.
 Use the provided tools for filesystem and shell work. Never claim a tool action succeeded unless its result confirms success.`;
 const MAX_READ_BYTES = 1024 * 1024;
 const MAX_TOOL_OUTPUT = 200_000;
@@ -468,26 +468,27 @@ function isWithin(root, candidate) {
     const relative = path.relative(root, candidate);
     return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
-export function resolveEcagentToolPath(projectPath, candidate, forWrite = false, bootstrapAgentMdPath, fullaccess = false) {
+export function resolveEcagentToolPath(projectPath, candidate, forWrite = false, bootstrapAgentMdPath, fullaccess = false, personalMdPath) {
     const root = fs.realpathSync(projectPath);
     const resolved = path.resolve(root, candidate || '.');
     const allowedBootstrapFile = bootstrapAgentMdPath
         ? path.resolve(bootstrapAgentMdPath)
         : undefined;
-    const isBootstrapAgentMd = allowedBootstrapFile === resolved;
-    if (!fullaccess && !isWithin(root, resolved) && !isBootstrapAgentMd) {
+    const allowedPersonalFile = personalMdPath ? path.resolve(personalMdPath) : undefined;
+    const isManagedIdentityFile = resolved === allowedBootstrapFile || resolved === allowedPersonalFile;
+    if (!fullaccess && !isWithin(root, resolved) && !isManagedIdentityFile) {
         throw new Error(`Path is outside the project: ${candidate}`);
     }
-    if (isBootstrapAgentMd) {
+    if (isManagedIdentityFile) {
         const parent = path.dirname(resolved);
         const canonicalParent = fs.realpathSync(parent);
         if (!isWithin(parent, canonicalParent) || !isWithin(canonicalParent, parent)) {
-            throw new Error(`Bootstrap agent.md parent resolves outside its declared path: ${candidate}`);
+            throw new Error(`Managed identity file parent resolves outside its declared path: ${candidate}`);
         }
         if (fs.existsSync(resolved)) {
             const canonicalFile = fs.realpathSync(resolved);
             if (!isWithin(resolved, canonicalFile) || !isWithin(canonicalFile, resolved)) {
-                throw new Error(`Bootstrap agent.md resolves outside its declared path: ${candidate}`);
+                throw new Error(`Managed identity file resolves outside its declared path: ${candidate}`);
             }
         }
         return resolved;
@@ -550,7 +551,7 @@ async function walkFiles(root, signal) {
 function textResult(text, details = {}) {
     return { content: [{ type: 'text', text: truncate(text) }], details };
 }
-function createTools(env, projectPath, runtimeEnv, bootstrapAgentMdPath, fullaccess = false) {
+function createTools(env, projectPath, runtimeEnv, bootstrapAgentMdPath, fullaccess = false, personalMdPath) {
     const read = {
         name: 'Read', label: 'Read', description: 'Read a UTF-8 text file from the project.',
         parameters: Type.Object({
@@ -559,7 +560,7 @@ function createTools(env, projectPath, runtimeEnv, bootstrapAgentMdPath, fullacc
             limit: Type.Optional(Type.Number({ minimum: 1 })),
         }),
         async execute(_id, params, signal) {
-            const file = resolveEcagentToolPath(projectPath, params.file_path, false, bootstrapAgentMdPath, fullaccess);
+            const file = resolveEcagentToolPath(projectPath, params.file_path, false, bootstrapAgentMdPath, fullaccess, personalMdPath);
             const stat = await fs.promises.stat(file);
             if (stat.size > MAX_READ_BYTES)
                 throw new Error(`File exceeds ${MAX_READ_BYTES} byte read limit`);
@@ -625,7 +626,7 @@ function createTools(env, projectPath, runtimeEnv, bootstrapAgentMdPath, fullacc
         name: 'Write', label: 'Write', description: 'Create or completely overwrite a project file.',
         parameters: Type.Object({ file_path: Type.String(), content: Type.String() }), executionMode: 'sequential',
         async execute(_id, params, signal) {
-            const file = resolveEcagentToolPath(projectPath, params.file_path, true, bootstrapAgentMdPath, fullaccess);
+            const file = resolveEcagentToolPath(projectPath, params.file_path, true, bootstrapAgentMdPath, fullaccess, personalMdPath);
             await fs.promises.mkdir(path.dirname(file), { recursive: true });
             await fs.promises.writeFile(file, params.content, { encoding: 'utf8', signal });
             return textResult(`Wrote ${Buffer.byteLength(params.content)} bytes to ${path.relative(projectPath, file)}`, { file });
@@ -638,7 +639,7 @@ function createTools(env, projectPath, runtimeEnv, bootstrapAgentMdPath, fullacc
             replace_all: Type.Optional(Type.Boolean()),
         }), executionMode: 'sequential',
         async execute(_id, params, signal) {
-            const file = resolveEcagentToolPath(projectPath, params.file_path, false, bootstrapAgentMdPath, fullaccess);
+            const file = resolveEcagentToolPath(projectPath, params.file_path, false, bootstrapAgentMdPath, fullaccess, personalMdPath);
             const value = await fs.promises.readFile(file, { encoding: 'utf8', signal });
             if (!params.old_string)
                 throw new Error('old_string must not be empty');
@@ -858,7 +859,7 @@ export class EcagentRunner {
                 models,
                 model,
                 thinkingLevel: normalizeThinkingLevel(effort),
-                tools: createTools(nodeEnv, request.projectPath, request.runtimeEnv, request.modelOverride?.bootstrapAgentMdPath, fullaccess),
+                tools: createTools(nodeEnv, request.projectPath, request.runtimeEnv, request.modelOverride?.bootstrapAgentMdPath, fullaccess, request.modelOverride?.personalMdPath),
                 systemPrompt: [DEFAULT_SYSTEM_PROMPT, request.systemPromptAppend].filter(Boolean).join('\n\n'),
                 streamOptions: {
                     timeoutMs: this.config.timeoutMs,

package/dist/agents/gemini-runner.js

@@ -147,6 +147,7 @@ const GEMINI_EC_COMMAND_PATTERNS = [
     // quoted arguments.
     String.raw `\x00"command":"[ ]*ec[ ]+(?:[^"\x00;&|$()<>\x60\r\n\\]|\\(?:\\|"))*"\x00`,
 ];
+const GEMINI_BOOTSTRAP_PERSONA_COMMAND_PATTERN = String.raw `^\{\x00"command":"[ ]*ec[ ]+agent[ ]+persona(?:[ ]+show|[ ]+--(?:text|file)[ ]+(?:[^"\x00;&|$()<>\x60\r\n\\]|\\(?:\\|"))+)[ ]*"\x00\}$`;
 export function resolveGeminiPermissionProfile(value, bootstrap = false) {
     if (value === 'fullaccess')
         return { mode: 'fullaccess', approvalMode: 'yolo' };
@@ -186,6 +187,9 @@ function geminiExactShellCommandPattern(command) {
     // is_background or additional_permissions during bootstrap.
     return `^\\{\\x00"command":"[ ]*${escapeGeminiArgsRegex(command)}[ ]*"\\x00\\}$`;
 }
+function geminiManagedIdentityPathPattern(filePath) {
+    return geminiJsonFieldEqualsPattern(['file_path'], path.resolve(filePath));
+}
 function appendGeminiPolicyRule(lines, toolName, decision, priority, argsPattern) {
     lines.push('[[rule]]');
     lines.push(`toolName = ${Array.isArray(toolName) ? JSON.stringify(toolName) : JSON.stringify(toolName)}`);
@@ -194,7 +198,7 @@ function appendGeminiPolicyRule(lines, toolName, decision, priority, argsPattern
     lines.push(`decision = "${decision}"`);
     lines.push(`priority = ${priority}`, '');
 }
-export function buildGeminiAdminPolicy(profile, bootstrapAgentMdPath) {
+export function buildGeminiAdminPolicy(profile, bootstrapAgentMdPath, personalMdPath) {
     const lines = [];
     if (bootstrapAgentMdPath) {
         const bootstrap = normalizeGeminiBootstrapAgentMdPath(bootstrapAgentMdPath);
@@ -212,6 +216,12 @@ export function buildGeminiAdminPolicy(profile, bootstrapAgentMdPath) {
         appendGeminiPolicyRule(lines, GEMINI_BOOTSTRAP_FILE_TOOLS, 'allow', 990, writePathPattern);
         appendGeminiPolicyRule(lines, 'run_shell_command', 'allow', 990, geminiExactShellCommandPattern(`ec aid agentmd put ${bootstrap.aid}`));
         appendGeminiPolicyRule(lines, 'run_shell_command', 'allow', 990, geminiExactShellCommandPattern(`ec agent ready ${bootstrap.aid}`));
+        appendGeminiPolicyRule(lines, 'run_shell_command', 'allow', 990, GEMINI_BOOTSTRAP_PERSONA_COMMAND_PATTERN);
+        if (personalMdPath) {
+            const personalPathPattern = geminiManagedIdentityPathPattern(personalMdPath);
+            appendGeminiPolicyRule(lines, 'read_file', 'allow', 989, personalPathPattern);
+            appendGeminiPolicyRule(lines, GEMINI_BOOTSTRAP_FILE_TOOLS, 'allow', 989, personalPathPattern);
+        }
         // These are Gemini's non-I/O task bookkeeping tools. They do not expose
         // project files, shell, network, MCP, or user-interaction capabilities.
         appendGeminiPolicyRule(lines, GEMINI_BOOTSTRAP_LIFECYCLE_TOOLS, 'allow', 950);
@@ -231,6 +241,11 @@ export function buildGeminiAdminPolicy(profile, bootstrapAgentMdPath) {
     for (const pattern of GEMINI_L_CLASS_PATTERNS) {
         appendGeminiPolicyRule(lines, GEMINI_L_CLASS_WRITE_TOOLS, 'deny', 997, pattern);
     }
+    if (personalMdPath) {
+        const personalPathPattern = geminiManagedIdentityPathPattern(personalMdPath);
+        appendGeminiPolicyRule(lines, 'read_file', 'allow', 989, personalPathPattern);
+        appendGeminiPolicyRule(lines, GEMINI_BOOTSTRAP_FILE_TOOLS, 'allow', 989, personalPathPattern);
+    }
     if (profile.mode === 'readonly') {
         appendGeminiPolicyRule(lines, GEMINI_READONLY_TOOLS, 'allow', 950);
         appendGeminiPolicyRule(lines, '*', 'deny', 900);
@@ -365,6 +380,9 @@ export class GeminiRunner {
         const bootstrapAgentMdPath = modelOverride?.bootstrapAgentMdPath
             ? normalizeGeminiBootstrapAgentMdPath(modelOverride.bootstrapAgentMdPath).filePath
             : undefined;
+        const personalMdPath = modelOverride?.personalMdPath
+            ? path.resolve(modelOverride.personalMdPath)
+            : undefined;
         const permissionProfile = resolveGeminiPermissionProfile(requestedPermissionMode, !!bootstrapAgentMdPath);
         const callModel = modelOverride?.model || this.model;
         const managedTaskTmpDir = getManagedTaskTempDir(runtimeEnv);
@@ -382,6 +400,7 @@ export class GeminiRunner {
                 ...(runtimeDir ? [runtimeDir] : []),
                 ...(runtimeLockDir ? [runtimeLockDir] : []),
                 ...(bootstrapAgentMdPath ? [bootstrapAgentMdPath] : []),
+                ...(personalMdPath ? [personalMdPath] : []),
             ],
         });
         if (executionPermissionMode !== 'fullaccess' && !sandboxProbe && workspaceContainsHClassPaths(projectPath)) {
@@ -410,7 +429,7 @@ export class GeminiRunner {
             }
             else {
                 const policyPath = path.join(managedTmpDir, `evolcore-gemini-permission-${crypto.randomUUID()}.toml`);
-                fs.writeFileSync(policyPath, buildGeminiAdminPolicy(permissionProfile, bootstrapAgentMdPath), { mode: 0o600, flag: 'wx' });
+                fs.writeFileSync(policyPath, buildGeminiAdminPolicy(permissionProfile, bootstrapAgentMdPath, personalMdPath), { mode: 0o600, flag: 'wx' });
                 tempFiles.push(policyPath);
                 args.push(...buildGeminiPermissionArgs(permissionProfile, policyPath, !!sandboxProbe));
             }
@@ -452,6 +471,7 @@ export class GeminiRunner {
                 ...(runtimeDir ? [runtimeDir] : []),
                 ...(runtimeLockDir ? [runtimeLockDir] : []),
                 ...(bootstrapAgentMdPath ? [bootstrapAgentMdPath] : []),
+                ...(personalMdPath ? [personalMdPath] : []),
             ],
             readonlyPaths: tempFiles,
         });

package/dist/aun/aid/agentmd.js

@@ -4,6 +4,51 @@ import { parseDocument } from 'yaml';
 import { getAidStore, loadAid, SLOT } from './store.js';
 import { agentMdPath, aidLocalDir, resolveRoot } from '../../paths.js';
 export const DEFAULT_AGENT_DESCRIPTION = 'EvolCore AI agent.';
+export const AGENT_TAG_MIN_COUNT = 3;
+export const AGENT_TAG_MAX_COUNT = 6;
+export const AGENT_TAG_MAX_LENGTH = 50;
+const AGENT_TAG_PATTERN = /^[\p{L}\p{N}]+$/u;
+/** Return a human-readable validation error for one tag, or null when valid. */
+export function validateAgentTag(tag) {
+    if (typeof tag !== 'string' || !tag.trim())
+        return 'must be a non-empty string';
+    const normalized = tag.trim();
+    if (Array.from(normalized).length > AGENT_TAG_MAX_LENGTH) {
+        return `must be at most ${AGENT_TAG_MAX_LENGTH} characters`;
+    }
+    if (!AGENT_TAG_PATTERN.test(normalized)) {
+        return 'must contain only Unicode letters and numbers';
+    }
+    return null;
+}
+/**
+ * Validate an agent.md tags value. Count constraints are optional because
+ * existing published agent.md files may contain fewer than three tags.
+ */
+export function validateAgentTags(tags, options = {}) {
+    if (!Array.isArray(tags))
+        return ['must be an array of strings'];
+    const errors = [];
+    const normalized = new Set();
+    tags.forEach((tag, index) => {
+        const error = validateAgentTag(tag);
+        if (error) {
+            errors.push(`tag ${index + 1} ${error}`);
+            return;
+        }
+        const value = tag.trim();
+        normalized.add(value);
+    });
+    const minCount = options.minCount;
+    const maxCount = options.maxCount;
+    if (minCount !== undefined && normalized.size < minCount) {
+        errors.push(`must contain at least ${minCount} unique tags`);
+    }
+    if (maxCount !== undefined && normalized.size > maxCount) {
+        errors.push(`must contain at most ${maxCount} unique tags`);
+    }
+    return errors;
+}
 const displayNameCache = new Map();
 const displayNamePending = new Map();
 const displayNameRevision = new Map();
@@ -87,7 +132,12 @@ export function buildInitialAgentMd(opts) {
     const agentName = opts.name?.trim() || opts.aid.split('.')[0];
     const agentType = opts.type || 'ai';
     const description = opts.description?.trim() || DEFAULT_AGENT_DESCRIPTION;
-    return `---\naid: ${yamlDoubleQuote(opts.aid)}\nname: ${yamlDoubleQuote(agentName)}\ntype: ${yamlDoubleQuote(agentType)}\nversion: "1.0.0"\ndescription: ${yamlDoubleQuote(description)}\ntags:\n  - evolcore\n---\n`;
+    const rawTags = opts.tags?.length ? opts.tags : ['evolcore'];
+    const tagErrors = validateAgentTags(rawTags);
+    if (tagErrors.length > 0)
+        throw new Error(`Invalid agent.md tags: ${tagErrors.join('; ')}`);
+    const tags = [...new Set(rawTags.map(tag => tag.trim()))];
+    return `---\naid: ${yamlDoubleQuote(opts.aid)}\nname: ${yamlDoubleQuote(agentName)}\ntype: ${yamlDoubleQuote(agentType)}\nversion: "1.0.0"\ndescription: ${yamlDoubleQuote(description)}\ntags:\n${tags.map(tag => `  - ${yamlDoubleQuote(tag)}\n`).join('')}---\n`;
 }
 function ensureTrailingNewline(content) {
     return content.endsWith('\n') ? content : `${content}\n`;
@@ -145,9 +195,11 @@ export function validateAgentMdFrontmatter(content, expectedAid) {
     if (description && description.length > 100) {
         errors.push('agent.md frontmatter description must be at most 100 characters');
     }
-    if (values.tags !== undefined && (!Array.isArray(values.tags)
-        || values.tags.some(tag => typeof tag !== 'string' || !tag.trim()))) {
-        errors.push('agent.md frontmatter tags must be an array of non-empty strings');
+    if (values.tags !== undefined) {
+        const tagErrors = validateAgentTags(values.tags);
+        if (tagErrors.length > 0) {
+            errors.push(`agent.md frontmatter tags ${tagErrors.join('; ')}`);
+        }
     }
     return { valid: errors.length === 0, errors };
 }

package/dist/aun/aid/index.js

@@ -1,3 +1,4 @@
+export { AGENT_TAG_MIN_COUNT, AGENT_TAG_MAX_COUNT, AGENT_TAG_MAX_LENGTH, validateAgentTag, validateAgentTags, } from './agentmd.js';
 export { isValidAid, aidList, aidListVerified, aidCreate, aidShow, aidDelete, aidLookup, verifySignAbility, probePkiRecoverability, appendAidLifecycle, readAidLifecycle } from './identity.js';
 export { DEFAULT_AGENT_DESCRIPTION, buildInitialAgentMd, validateAgentMdFrontmatter, agentmdGet, agentmdPut, agentmdSync, invalidateAgentDisplayName, parseAgentDisplayName, refreshAgentDisplayName, resolveAgentDisplayName, stripAgentMdSignature, updateAgentMdFrontmatterAvatar, updateAgentMdFrontmatterName, } from './agentmd.js';
 export { MIN_AUN_CORE_SDK, AUN_CORE_SDK_PKG, isAunSdkVersionOk, resolveAunCoreSdkPkg, ensureAunSdk, isAunSdkReady, downloadCaRoot, suppressSdkLogs, } from './client.js';

package/dist/aun/aid/managed-operation.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolveRoot } from '../../paths.js';
 import { agentmdGet, agentmdPut } from './agentmd.js';
+import { uploadAvatarBuffer, uploadAvatarUrl } from '../../utils/avatar-upload.js';
 import { aidLookup, aidShow } from './identity.js';
 import { isValidAid } from './validation.js';
 export class ManagedAidOperationError extends Error {
@@ -28,6 +29,32 @@ function parseAid(value) {
         return { ok: false, code: 'INVALID_AID', reason: `invalid AID: ${aid}` };
     return { ok: true, aid };
 }
+function parseAvatar(args) {
+    const aidResult = parseAid(args[1]);
+    if (!aidResult.ok)
+        return aidResult;
+    const sourceFlag = args[2];
+    const sourceValue = args[3];
+    if (sourceFlag !== '--file' && sourceFlag !== '--url') {
+        return { ok: false, code: 'INVALID_ARGUMENT', reason: 'avatar requires exactly one of --file <path> or --url <https-url>' };
+    }
+    if (!sourceValue || sourceValue.startsWith('-')) {
+        return { ok: false, code: 'INVALID_ARGUMENT', reason: `${sourceFlag} requires a non-empty value` };
+    }
+    if (args.length !== 4 && !(args.length === 6 && args[4] === '--format' && args[5] === 'json')) {
+        return { ok: false, code: 'NOT_ALLOWED', reason: 'avatar only supports an optional --format json suffix' };
+    }
+    return {
+        ok: true,
+        command: {
+            kind: 'avatar',
+            aid: aidResult.aid,
+            ...(sourceFlag === '--file' ? { filePath: sourceValue } : { url: sourceValue }),
+            operationId: 'ec.aid.avatar',
+            canonicalArgv: ['aid', 'avatar', aidResult.aid, sourceFlag, sourceValue],
+        },
+    };
+}
 /**
  * The daemon accepts only the narrowly scoped AID commands exposed to managed
  * tasks. Public lookup/get may name any valid AID; local show/publish remain
@@ -36,6 +63,8 @@ function parseAid(value) {
 export function resolveManagedAidOperation(argv) {
     const args = argv[0] === 'aid' ? argv.slice(1) : argv;
     const subcommand = args[0];
+    if (subcommand === 'avatar')
+        return parseAvatar(args);
     if ((subcommand === 'show' || subcommand === 'lookup') && hasOnlyOptionalJsonFormat(args, 1)) {
         const parsedAid = parseAid(args[1]);
         if (!parsedAid.ok)
@@ -68,7 +97,7 @@ export function resolveManagedAidOperation(argv) {
     return {
         ok: false,
         code: 'NOT_ALLOWED',
-        reason: 'Managed AID operations only allow exact show, lookup, agentmd get, or agentmd put commands with an optional --format json suffix',
+        reason: 'Managed AID operations only allow exact show, lookup, agentmd get, agentmd put, or avatar commands with supported options',
     };
 }
 export function managedAidShowViewForRole(role) {
@@ -93,6 +122,8 @@ const defaultDependencies = () => ({
     agentmdPut,
     existsSync: fs.existsSync,
     readFileSync: fs.readFileSync,
+    uploadAvatarBuffer,
+    uploadAvatarUrl,
 });
 /** Execute a validated AID operation from the daemon-owned host filesystem. */
 export async function executeManagedAidOperation(command, options = {}) {
@@ -125,5 +156,26 @@ export async function executeManagedAidOperation(command, options = {}) {
             await deps.agentmdPut(content, { aid: command.aid, aunPath });
             return { kind: command.kind, aid: command.aid, path: localPath };
         }
+        case 'avatar': {
+            const result = command.url
+                ? await deps.uploadAvatarUrl(command.aid, command.url, { aunPath })
+                : await deps.uploadAvatarBuffer(command.aid, options.avatarBuffer ?? deps.readFileSync(command.filePath), { aunPath });
+            if (!result.ok) {
+                throw new ManagedAidOperationError(result.code ?? 'UPLOAD_FAILED', result.error ?? 'avatar upload failed');
+            }
+            return {
+                kind: 'avatar',
+                aid: command.aid,
+                avatar: result.publicUrl,
+                objectKey: result.objectKey,
+                sha256: result.sha256,
+                mime: result.mime,
+                width: result.width,
+                height: result.height,
+                aspectRatio: result.aspectRatio,
+            };
+        }
+        default:
+            throw new ManagedAidOperationError('NOT_ALLOWED', `Unsupported managed AID operation: ${command.kind}`);
     }
 }

package/dist/aun/storage/client.js

@@ -17,7 +17,10 @@ function pickUrl(value) {
     return typeof value === 'string' && value.trim() ? value : undefined;
 }
 export async function storageUpload(aid, localFile, remotePath, opts) {
-    const fileBuffer = fs.readFileSync(localFile);
+    const fileBuffer = Buffer.isBuffer(localFile) ? localFile : fs.readFileSync(localFile);
+    return storageUploadBuffer(aid, fileBuffer, remotePath, opts);
+}
+export async function storageUploadBuffer(aid, fileBuffer, remotePath, opts) {
     const contentType = opts?.contentType ?? 'application/octet-stream';
     const sha256 = crypto.createHash('sha256').update(fileBuffer).digest('hex');
     const createResult = await rpcCall(aid, 'storage.create_upload_session', {

package/dist/aun/storage/index.js

@@ -1,2 +1,2 @@
-export { storageUpload, storageLs, storageRm, storageQuota } from './client.js';
+export { storageUpload, storageUploadBuffer, storageLs, storageRm, storageQuota } from './client.js';
 export { storageDownload } from './download.js';