editmamei 1.4.0 → 1.5.1

package/README.md

@@ -9,7 +9,7 @@
 [![License](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](LICENSE.md)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-lightgrey.svg)](docs/installation.md)
 
-Editmamei is a Model Context Protocol (MCP) server that drives the Adobe Photoshop you already have. You describe the edit in plain words, your AI assistant plans the steps, and your own copy of Photoshop carries them out with its standard adjustment layers, masks, selections, and filters. The AI directs and Photoshop edits. No generative model touches your pixels, and no image is uploaded to perform an edit.
+Editmamei is a Model Context Protocol (MCP) server that drives desktop Adobe Photoshop. You describe the edit in plain words, your AI assistant plans the steps, and Photoshop carries them out with its standard adjustment layers, masks, selections, and filters. The AI directs and Photoshop edits. No generative model touches your pixels, and no image is uploaded to perform an edit.
 
 It serves photographers and retouchers who want to edit by conversation just as much as developers wiring Photoshop into an AI pipeline. To learn more or get started, visit **[editmamei.com](https://editmamei.com)**.
 
@@ -47,7 +47,7 @@ Then restart your AI client and ask it: _"Is Photoshop connected?"_
 
 Prefer not to use a terminal? Claude Desktop users can install the one-click [`.mcpb` extension](https://github.com/editmamei/editmamei/releases/latest/download/editmamei.mcpb) directly (no system Node required, Claude Desktop ships its own runtime). Full walkthrough in the [install guide](docs/installation.md).
 
-**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 13+, Node.js 22+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code).
+**Requirements:** Adobe Photoshop 2026 (v27.x), Windows 10/11 or macOS 13+, Node.js 22+ (for the npm path), and an MCP-compatible AI client (Claude Desktop, Cursor, Claude Code). Editmamei ships no model of its own and runs on whichever client you connect, so every edit spends that client's tokens.
 
 ## A session, end to end
 
@@ -75,7 +75,7 @@ These are the choices that shape the surface, and the reason an AI assistant can
 
 ## Tool surface
 
-**82 tools across 16 capability groups** (62 Community, 20 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
+**83 tools across 16 capability groups** (62 Community, 21 Pro). Every tool is namespaced `ps_*` and discoverable at runtime via `tools/list`. Community tools ship in both editions; Pro tools unlock with a license.
 
 | Group | Edition | Tools |
 | --- | --- | --- |
@@ -94,7 +94,7 @@ These are the choices that shape the surface, and the reason an AI assistant can
 | **AI selection** | Community | `select_subject` · `select_sky` · `replace_sky` |
 | **Automation** | Community | `sequence` |
 | **AI selection** | Pro | `select_subject_instance` · `select_object` |
-| **Filters** | Pro | `apply_camera_raw` |
+| **Filters** | Pro | `apply_camera_raw` · `develop_raw` |
 | **Layers (warp)** | Pro | `warp_layer` |
 | **Perception** | Pro | `edit_object` · `add_text_to_object` · `resolve_placement` |
 | **Face mesh** | Pro | `detect_landmarks` · `select_face_feature` |
@@ -132,7 +132,7 @@ Settings live in `~/.editmamei/settings.json`, managed by the `editmamei config`
 
 ```bash
 editmamei config list
-editmamei config set telemetry.usage false      # turn off anonymous usage telemetry
+editmamei config set telemetry.usage false      # turn off usage telemetry
 editmamei config set ps_path "/path/to/Photoshop"
 ```
 
@@ -140,7 +140,7 @@ editmamei config set ps_path "/path/to/Photoshop"
 
 ## Privacy
 
-Editmamei runs on your computer and edits in your own Photoshop. No image content, document data, or file paths are sent to Editmamei's servers. It reports anonymous, content-free usage telemetry (on by default, turn it off with `editmamei config set telemetry.usage false`). When your AI assistant needs to see a result, Editmamei sends it a downscaled preview, the same as dropping a photo into a chat with that assistant. Every field is documented in [privacy.md](docs/privacy.md).
+Editmamei runs on your computer and edits in desktop Photoshop. No image content, document data, or file paths are sent to Editmamei's servers. It reports content-free usage telemetry (on by default, turn it off with `editmamei config set telemetry.usage false`). When your AI assistant needs to see a result, Editmamei sends it a downscaled preview, the same as dropping a photo into a chat with that assistant. Every field is documented in [privacy.md](docs/privacy.md), including [your rights, and the legal basis](docs/privacy.md#your-rights-and-the-legal-basis).
 
 The source in this repository is the same code published to npm, so none of the above has to be taken on trust.
 
@@ -150,6 +150,7 @@ The source in this repository is the same code published to npm, so none of the
 - **Install:** [docs/installation.md](docs/installation.md)
 - **Getting started:** [docs/getting-started.md](docs/getting-started.md)
 - **FAQ:** [docs/faq.md](docs/faq.md)
+- **Troubleshooting:** [docs/troubleshooting.md](docs/troubleshooting.md)
 - **Pro features:** [docs/pro-features.md](docs/pro-features.md)
 - **Roadmap:** [docs/roadmap.md](docs/roadmap.md)
 - **Bugs and feature requests:** [the issue tracker](https://github.com/editmamei/editmamei/issues). If something's broken, ask your assistant to "report a problem" (or run `editmamei report`) to drop an anonymized diagnostic bundle in your Downloads folder, then attach it to the issue.

package/dist/cli/help.js

@@ -33,7 +33,7 @@ Install options:
 
 Config examples:
   editmamei config list                          Show all settings
-  editmamei config set telemetry.usage false     Opt out of anonymous usage telemetry
+  editmamei config set telemetry.usage false     Opt out of usage telemetry
   editmamei config set telemetry.diagnostics true Opt in to sanitized diagnostic detail
 
 Report options:

package/dist/core/server.js

@@ -8,16 +8,18 @@ import { groupOf, GROUPS } from './tool-groups.js';
 import { EDITION } from '../edition.js';
 import { VERSION } from '../version.js';
 import { Session } from './session.js';
-import { SessionLog, classifyError, NO_ERROR_TEXT_CLASS } from '../utils/session-log.js';
+import { SessionLog, classifyError, computeResultBytes, NO_ERROR_TEXT_CLASS, } from '../utils/session-log.js';
 import { loadSettings, applyTelemetryEnvOverrides, applyUpdateCheckEnvOverride, } from './settings.js';
 import { TelemetryClient } from '../telemetry/client.js';
 import { resolveInstallChannel } from '../install-channel.js';
-import { checkForUpdate, shouldCheckForUpdate } from '../update/check.js';
+import { checkForUpdateWithStatus, shouldCheckForUpdate, } from '../update/check.js';
 import { previousSessionFailureCounts, relevantFixes } from '../update/session-fixes.js';
 import { join } from 'node:path';
+import { createHash } from 'node:crypto';
 import { GoSnippetClient, coreBinaryName } from '../api/snippet-client.js';
 import { isProEntitled } from '../license/entitlement.js';
 import { createPingLicenseRefresher } from '../license/ping-refresh.js';
+import { licenseAdvisory } from '../license/advisory.js';
 import { runScript } from '../utils/run-script.js';
 import { listTemplates } from '../utils/template-storage.js';
 import { toolErrorResult } from '../utils/tool-helpers.js';
@@ -42,9 +44,20 @@ function warnLogScriptOnErrorOnce(logger) {
 export function __resetLogScriptOnErrorWarnForTests() {
     logScriptOnErrorWarned = false;
 }
-const FIRST_RUN_DISCLOSURE = 'First run: Editmamei collects anonymous, content-free usage telemetry (tool name, ' +
-    'success, duration, version/edition/OS/PS-version, install channel) to find what breaks. ' +
-    'It never sends image content, file paths, or personal data. Opt out anytime: ' +
+function hashRetryKey(tool, args) {
+    try {
+        const json = JSON.stringify({ tool, args });
+        return createHash('sha256').update(json).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+export const FIRST_RUN_DISCLOSURE = 'First run: Editmamei collects content-free usage telemetry (tool name, ' +
+    'success, duration, bytes returned, version/edition/OS/PS-version, install channel, ' +
+    'which AI client connected, Node/OS/architecture versions, and per-session counts like ' +
+    'edits made and retries) to find what breaks. It never sends image content, file paths, ' +
+    'or tool arguments. The only identifier is a random install ID. Opt out anytime: ' +
     '`editmamei config set telemetry.usage false` (or edit ~/.editmamei/settings.json). ' +
     'Opt in to sanitized diagnostics: `editmamei config set telemetry.diagnostics true`.';
 export const BACKGROUND_VERSION_PROBE_TIMEOUT_MS = 3_000;
@@ -62,13 +75,22 @@ export class EditmameiServer {
     }
     psVersion = null;
     lastPingReachedPs = null;
+    lastTelemetryCallKeyHash = null;
+    lastPsLocale = null;
+    lastDocDepth = null;
+    lastDocMode = null;
     liveVersionResolutionAttempted = false;
     updateInfo = null;
     updateCheck = null;
     updateNoticeShown = false;
     snippetClient = new GoSnippetClient();
     refreshLicenseOnPing = createPingLicenseRefresher();
-    constructor() {
+    moduleUpdateFailed = false;
+    licenseAdvisorySource;
+    licenseStoreOptions;
+    licenseAdvisoryShown = false;
+    constructor(opts = {}) {
+        this.licenseStoreOptions = opts.licenseStore ?? {};
         this.logger = new Logger('EditmameiServer');
         this.session = new Session();
         this.sessionLog = new SessionLog(this.session.getSessionId());
@@ -84,10 +106,18 @@ export class EditmameiServer {
         });
         if (created)
             this.logger.info(FIRST_RUN_DISCLOSURE);
-        if (shouldCheckForUpdate(effectiveSettings.update_check)) {
-            this.updateCheck = checkForUpdate().then((info) => {
-                this.updateInfo = info;
-            });
+        const shouldCheckForUpdateFn = opts.shouldCheckForUpdate ?? shouldCheckForUpdate;
+        const checkForUpdateWithStatusFn = opts.checkForUpdateWithStatus ?? checkForUpdateWithStatus;
+        if (shouldCheckForUpdateFn(effectiveSettings.update_check)) {
+            this.updateCheck = checkForUpdateWithStatusFn()
+                .then((result) => {
+                this.updateInfo = result.info;
+                if (result.status === 'newer')
+                    this.telemetry.setBehindLatest(true);
+                else if (result.status === 'current')
+                    this.telemetry.setBehindLatest(false);
+            })
+                .catch(() => undefined);
         }
         warnLogScriptOnErrorOnce(this.logger);
         this.toolRegistry = new ToolRegistry({
@@ -97,22 +127,33 @@ export class EditmameiServer {
                         this.resolveLiveVersionInBackground();
                     }
                 }
-                void this.sessionLog.append({
+                const resultBytes = computeResultBytes(entry.result);
+                void this.sessionLog
+                    .append({
                     tool: entry.tool,
                     args: entry.args,
                     success: entry.success,
                     duration_ms: entry.duration_ms,
                     ...(entry.error ? { error: entry.error } : {}),
-                }, entry.result);
+                }, entry.result, resultBytes)
+                    .catch((err) => {
+                    this.logger.debug(`session log append failed: ${String(err)}`);
+                });
                 const telemetrySuccess = entry.tool === 'ps_ping' && this.lastPingReachedPs === false ? false : entry.success;
                 const isPingDowngrade = entry.tool === 'ps_ping' && !telemetrySuccess && entry.error === undefined;
                 const errorClass = classifyError(entry.error) ??
                     (telemetrySuccess ? null : isPingDowngrade ? 'ps_not_running' : NO_ERROR_TEXT_CLASS);
+                const telemetryCallKeyHash = hashRetryKey(entry.tool, entry.args);
+                const isTelemetryRetry = telemetryCallKeyHash !== null && telemetryCallKeyHash === this.lastTelemetryCallKeyHash;
+                if (telemetryCallKeyHash !== null)
+                    this.lastTelemetryCallKeyHash = telemetryCallKeyHash;
                 this.telemetry.recordCall({
                     tool: entry.tool,
                     success: telemetrySuccess,
                     duration_ms: entry.duration_ms,
                     error_class: errorClass,
+                    result_bytes: resultBytes,
+                    retry: isTelemetryRetry,
                 });
                 if (!telemetrySuccess) {
                     this.telemetry.recordDiagnostic({
@@ -122,6 +163,9 @@ export class EditmameiServer {
                             (isPingDowngrade
                                 ? 'ps_ping did not reach Photoshop'
                                 : 'tool reported failure with no message'),
+                        ...(this.lastPsLocale !== null ? { ps_locale: this.lastPsLocale } : {}),
+                        ...(this.lastDocDepth !== null ? { doc_depth: this.lastDocDepth } : {}),
+                        ...(this.lastDocMode !== null ? { doc_mode: this.lastDocMode } : {}),
                     });
                 }
             },
@@ -136,9 +180,44 @@ export class EditmameiServer {
         });
         const srv = this.server;
         this.sessionLog.setMcpClientGetter(() => srv.getClientVersion?.() ?? null);
+        let clientConnectedSent = false;
+        this.server.oninitialized = () => {
+            if (clientConnectedSent)
+                return;
+            clientConnectedSent = true;
+            const clientInfo = this.server.getClientVersion();
+            const caps = this.server.getClientCapabilities();
+            this.telemetry.recordClientConnected({
+                clientName: clientInfo?.name,
+                clientVersion: clientInfo?.version,
+                capSampling: caps?.sampling != null,
+                capElicitation: caps?.elicitation != null,
+                capRoots: caps?.roots != null,
+            });
+        };
+        this.licenseAdvisorySource =
+            opts.licenseAdvisory ??
+                ((advisoryOpts) => {
+                    if (process.env.VITEST !== undefined || process.env.NODE_ENV === 'test')
+                        return null;
+                    return licenseAdvisory(advisoryOpts);
+                });
         this.registerTools();
         this.setupHandlers();
     }
+    buildLicenseAdvisoryNote() {
+        if (this.licenseAdvisoryShown)
+            return { note: '', stamp: () => { } };
+        const text = this.licenseAdvisorySource({ moduleUpdateFailed: this.moduleUpdateFailed });
+        if (!text)
+            return { note: '', stamp: () => { } };
+        return {
+            note: ' ' + text,
+            stamp: () => {
+                this.licenseAdvisoryShown = true;
+            },
+        };
+    }
     registerTools() {
         this.toolRegistry.register('ps_ping', {
             tool: {
@@ -221,8 +300,14 @@ export class EditmameiServer {
         this.moduleLifecycle = new ModuleLifecycle({
             toolRegistry: this.toolRegistry,
             logger: this.logger,
+            licenseStore: this.licenseStoreOptions,
             assertToolsClassified: () => this.assertToolsClassified(),
             classifyTool: (name) => this.classifyTool(name),
+            onModuleUpdate: (outcome) => {
+                if (outcome === 'failed')
+                    this.moduleUpdateFailed = true;
+                this.telemetry.setModuleUpdate(outcome);
+            },
         });
         const proModule = this.moduleLifecycle.resolveProModule();
         this.kernel = new Kernel({
@@ -332,6 +417,11 @@ export class EditmameiServer {
                 clearPendingRawDevelop();
             }
         }
+        else if (name === 'ps_develop_raw') {
+            const sc = result.structuredContent;
+            if (sc?.opened === true)
+                clearPendingRawDevelop();
+        }
         else if (name === 'ps_apply_camera_raw' || name === 'ps_close_document') {
             clearPendingRawDevelop();
         }
@@ -366,12 +456,22 @@ export class EditmameiServer {
         if (this.updateCheck)
             await this.updateCheck;
         const update = await this.buildUpdateNotice();
+        const advisory = this.buildLicenseAdvisoryNote();
+        const withAdvisory = (text) => {
+            advisory.stamp();
+            return text + advisory.note;
+        };
         const connection = this.session.getConnection();
         let version = 'Unknown';
         let actionSetsCount = 0;
+        let actionSetsObserved = false;
         let openDocuments = [];
+        let psLocale = null;
+        let docDepth = null;
+        let docMode = null;
         const degraded = [];
         let versionIsLive = false;
+        let pingStateObserved = false;
         try {
             const detected = await connection.getVersion();
             if (detected)
@@ -381,12 +481,14 @@ export class EditmameiServer {
         }
         if (connection.getPhotoshopInfo() !== null && !(await connection.isCurrentlyRunning())) {
             this.lastPingReachedPs = false;
+            this.lastDocDepth = null;
+            this.lastDocMode = null;
             return {
                 content: [
                     {
                         type: 'text',
-                        text: 'Photoshop does not appear to be running. Start Photoshop, then call ps_ping again.' +
-                            update.note,
+                        text: withAdvisory('Photoshop does not appear to be running. Start Photoshop, then call ps_ping again.' +
+                            update.note),
                     },
                 ],
                 structuredContent: {
@@ -406,11 +508,13 @@ export class EditmameiServer {
             if (!alive) {
                 const reason = unsupportedHostReason();
                 this.lastPingReachedPs = false;
+                this.lastDocDepth = null;
+                this.lastDocMode = null;
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: (reason ?? 'Photoshop did not respond') + update.note,
+                            text: withAdvisory((reason ?? 'Photoshop did not respond') + update.note),
                         },
                     ],
                     structuredContent: {
@@ -430,8 +534,15 @@ export class EditmameiServer {
             catch (err) {
                 this.logger.warn(`pingState snippet failed: ${err instanceof Error ? err.message : String(err)}`);
                 this.lastPingReachedPs = false;
+                this.lastDocDepth = null;
+                this.lastDocMode = null;
                 return {
-                    content: [{ type: 'text', text: 'Photoshop did not respond' + update.note }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: withAdvisory('Photoshop did not respond' + update.note),
+                        },
+                    ],
                     structuredContent: {
                         connected: false,
                         update_available: this.updateInfo,
@@ -439,19 +550,36 @@ export class EditmameiServer {
                     },
                 };
             }
+            pingStateObserved = true;
             if (state.version) {
                 version = state.version;
                 versionIsLive = true;
             }
-            if (typeof state.action_sets_count === 'number')
+            if (typeof state.action_sets_count === 'number') {
                 actionSetsCount = state.action_sets_count;
+                actionSetsObserved = true;
+            }
             if (Array.isArray(state.open_documents))
                 openDocuments = state.open_documents;
+            if (typeof state.locale === 'string')
+                psLocale = state.locale;
+            if (state.doc_depth === 8 || state.doc_depth === 16 || state.doc_depth === 32) {
+                docDepth = state.doc_depth;
+            }
+            if (state.doc_mode === 'rgb' ||
+                state.doc_mode === 'cmyk' ||
+                state.doc_mode === 'lab' ||
+                state.doc_mode === 'grayscale' ||
+                state.doc_mode === 'other') {
+                docMode = state.doc_mode;
+            }
         }
         let userTemplates = 0;
+        let templatesObserved = false;
         try {
             const templates = await listTemplates();
             userTemplates = templates.length;
+            templatesObserved = true;
         }
         catch (err) {
             this.logger.warn(`listTemplates failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -464,17 +592,27 @@ export class EditmameiServer {
             this.psVersion = version;
             this.telemetry.onPsVersionResolved();
         }
+        if (psLocale !== null)
+            this.lastPsLocale = psLocale;
+        if (pingStateObserved) {
+            this.lastDocDepth = docDepth;
+            this.lastDocMode = docMode;
+        }
+        this.telemetry.setInstallAssets({
+            ...(templatesObserved ? { templates_saved: userTemplates } : {}),
+            ...(actionSetsObserved ? { action_sets: actionSetsCount } : {}),
+        });
         this.lastPingReachedPs = true;
         const degradedNote = degraded.length ? ` (degraded: ${degraded.join(', ')})` : '';
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Connected to Photoshop (v${version}). ` +
+                    text: withAdvisory(`Connected to Photoshop (v${version}). ` +
                         `${actionSetsCount} custom action set(s), ${userTemplates} saved template(s), ` +
                         `${openDocuments.length} open document(s)${openDocuments.length ? ': ' + openDocuments.join(', ') : ''}` +
                         `${degradedNote}.` +
-                        update.note,
+                        update.note),
                 },
             ],
             structuredContent: {

package/dist/core/tool-groups.js

@@ -117,6 +117,7 @@ export const TOOL_GROUPS = {
     ps_apply_adjustment: 'adjust',
     ps_filter: 'filter',
     ps_apply_camera_raw: 'filter',
+    ps_develop_raw: 'filter',
     ps_retouch: 'retouch',
     ps_apply_brush_stroke: 'retouch',
     ps_create_layer: 'layers',

package/dist/core/tool-tiers.js

@@ -45,6 +45,7 @@ export const TOOL_TIERS = {
     ps_warp_layer_region: 'pro',
     ps_warp_layer_to: 'pro',
     ps_apply_camera_raw: 'pro',
+    ps_develop_raw: 'pro',
     ps_transform_canvas: 'community',
     ps_guides: 'community',
     ps_inspect: 'community',

package/dist/install-channel.js

@@ -1,8 +1,58 @@
+import { realpathSync } from 'node:fs';
 import { EDITION } from './edition.js';
-export function resolveInstallChannel(env = process.env, edition = EDITION) {
+function pathSegments(path) {
+    return path
+        .split(/[\\/]/)
+        .filter((s) => s.length > 0)
+        .map((s) => s.toLowerCase());
+}
+function defaultRealpath(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+function safeRealpath(p, realpath) {
+    try {
+        return realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+function prefixMatches(execDirSegments, entryPrefixSegments) {
+    return (execDirSegments.length > 0 && execDirSegments.every((seg, i) => entryPrefixSegments[i] === seg));
+}
+export function resolveInstallChannel(env = process.env, edition = EDITION, argv1 = process.argv[1], execPath = process.execPath, realpath = defaultRealpath) {
     if (edition === 'dev')
         return 'dev';
     if (env.EDITMAMEI_INSTALL_CHANNEL === 'mcpb')
         return 'mcpb';
-    return 'npm';
+    const trimmedArgv1 = argv1?.trim();
+    if (!trimmedArgv1)
+        return 'unknown';
+    const resolvedArgv1 = safeRealpath(trimmedArgv1, realpath);
+    const segments = pathSegments(resolvedArgv1);
+    if (segments.includes('_npx'))
+        return 'npx';
+    const nodeModulesIdx = segments.indexOf('node_modules');
+    if (nodeModulesIdx === -1)
+        return 'source';
+    const precedingSegment = nodeModulesIdx > 0 ? segments[nodeModulesIdx - 1] : undefined;
+    if (precedingSegment === 'lib' || precedingSegment === 'npm')
+        return 'npm_global';
+    const resolvedExecPath = execPath === undefined ? undefined : safeRealpath(execPath, realpath);
+    const resolvedExecDir = pathSegments(resolvedExecPath ?? '').slice(0, -1);
+    const resolvedEntryPrefix = segments.slice(0, nodeModulesIdx);
+    const rawExecDir = execPath === undefined ? [] : pathSegments(execPath).slice(0, -1);
+    const rawArgv1Segments = pathSegments(trimmedArgv1);
+    const rawNodeModulesIdx = rawArgv1Segments.indexOf('node_modules');
+    const rawEntryPrefix = rawNodeModulesIdx === -1 ? [] : rawArgv1Segments.slice(0, rawNodeModulesIdx);
+    const underExecDir = prefixMatches(resolvedExecDir, resolvedEntryPrefix) ||
+        prefixMatches(rawExecDir, rawEntryPrefix);
+    if (underExecDir)
+        return 'npm_global';
+    return 'npm_local';
 }