@myagentroam/node 0.10.32 → 0.10.33

package/dist/database.js

@@ -1,4 +1,6 @@
 import { NODE_SCHEMA_MIGRATION_V17 } from './migrations/v017.js';
+import { NODE_SCHEMA_MIGRATION_V18 } from './migrations/v018.js';
+import { normalizeSessionPrompt } from './util/personal-instructions.js';
 import { randomUUID } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -16,7 +18,8 @@ export const NODE_SCHEMA_MIGRATIONS = [
     NODE_SCHEMA_MIGRATION_V14,
     NODE_SCHEMA_MIGRATION_V15,
     NODE_SCHEMA_MIGRATION_V16,
-    NODE_SCHEMA_MIGRATION_V17
+    NODE_SCHEMA_MIGRATION_V17,
+    NODE_SCHEMA_MIGRATION_V18
 ];
 const LEGACY_NODE_SCHEMA_V12 = NODE_SCHEMA_VERSION_V13 - 1;
 const OBSOLETE_NODE_SCHEMA_V16 = 16;
@@ -266,6 +269,9 @@ export class NodeDatabase {
         const runnerTitle = input.runnerTitle === undefined
             ? (current?.runnerTitle ?? null)
             : input.runnerTitle?.trim() || null;
+        const sessionPrompt = input.sessionPrompt === undefined
+            ? (current?.sessionPrompt ?? null)
+            : normalizeSessionPrompt(input.sessionPrompt);
         const runnerTitlePending = input.runnerTitlePending === undefined
             ? (current?.runnerTitlePending ?? false)
             : input.runnerTitlePending;
@@ -285,6 +291,7 @@ export class NodeDatabase {
         const metadata = JSON.stringify({
             version: 1,
             customTitle,
+            sessionPrompt,
             runnerTitle,
             runnerTitlePending,
             model,
@@ -321,6 +328,7 @@ export class NodeDatabase {
         }
         return {
             customTitle,
+            sessionPrompt,
             runnerTitle,
             runnerTitlePending,
             pinnedAt: pinOrder === null ? null : 1,
@@ -564,6 +572,7 @@ function sessionMetadata(row) {
     const value = (key) => typeof raw[key] === 'string' ? raw[key] : null;
     return {
         customTitle: value('customTitle'),
+        sessionPrompt: value('sessionPrompt'),
         runnerTitle: value('runnerTitle'),
         runnerTitlePending: raw['runnerTitlePending'] === true,
         model: value('model'),

package/dist/migrations/v018.js

@@ -0,0 +1,9 @@
+import { NODE_SCHEMA_MIGRATION_V17 } from './v017.js';
+export const NODE_SCHEMA_MIGRATION_V18 = {
+    version: 18,
+    sql: `UPDATE agent_sessions
+    SET metadata = json_set(metadata, '$.sessionPrompt', NULL)
+    WHERE json_type(metadata, '$.sessionPrompt') IS NULL;`,
+    preflight: (database) => NODE_SCHEMA_MIGRATION_V17.assert(database),
+    assert: (database) => NODE_SCHEMA_MIGRATION_V17.assert(database)
+};

package/dist/runner/mar-agent/marctl-skill.js

@@ -17,15 +17,16 @@ export function marctlHostSkill(environment = {}) {
 }
 const marctlInstructions = [
     '## MAR Workspace CLI',
-    'Use exec to run marctl. Start with marctl sessions current --json and marctl sessions list --json. Local marctl help sessions and marctl --version work without a network request. Read the installed help for exact options; capabilities and permissions still apply.',
+    'Use exec to run marctl. Reuse loaded guidance while it remains in context. Consult local marctl help sessions for unclear options and marctl --version when version matters; neither needs a network request. Capabilities and permissions still apply.',
+    'Use sessions current --json only when the current identity or scope is unknown. For a known target ID, use sessions show <session-id> --json only when fresh state is needed, without current/list first. Use sessions list --limit 10 --json to discover an unknown target; list has no name-search option. Stop once found and follow nextCursor only if needed. Do not scan the Workspace to prove capacity: check assigned work, recorded worker IDs and overlapping write scopes.',
     'MAR binds sessions to the current Node and Workspace. No --node or --workspace override exists. Use returned native Session IDs, not titles, for later operations. A Workspace terminal may have no current Session. Missing scope, an old Node, expired authorization or an unavailable Runner is an explicit error, not permission to bypass the API.',
     '## Create and coordinate independent Sessions',
-    'Use -m / --message for direct text, or --message-file for a UTF-8 file (- reads stdin); these options are mutually exclusive. Create a Session with marctl sessions start --runner codex --title "fixer#42 Handle empty totals" --message-file task.txt --json. Other Runner names are mar-agent, claude-code and opencode. An omitted model uses the target Runner configuration, not the Coordinator model.',
+    'Prefer -m / --message for short text; use --message-file for longer UTF-8 text or an existing file (- reads stdin). These options are mutually exclusive. Example: marctl sessions start --runner codex --title "fixer#42 Handle empty totals" -m "Implement issue #42 and report test evidence" --json. Other Runner names are mar-agent, claude-code and opencode. An omitted model uses the target Runner configuration, not the Coordinator model.',
     'For start/send, repeat --image <local-path> to attach PNG, JPEG, GIF or WebP images, with or without text. Images are read on this CLI host, not by remote path. Limits: 5 images, 5 MiB each, 10 MiB total. Actual Runner/model image capabilities apply; goal set accepts text only.',
-    'Create workers only as tasks need them. For Fixer/Reviewer work use fixer#<task-id> <description> and reviewer#<task-or-change-id> <description>. These are naming conventions, not product roles or a fixed worker pool. Put role, scope, acceptance criteria and delivery requirements in the first ordinary message. There is no Session custom prompt setting.',
-    'Use sessions show <session-id> --json for Run, queue and Goal state. Read bounded visible history with sessions history <session-id> --limit 10 --json; follow nextCursor only when needed. Hidden reasoning, credentials and raw model requests are not collaboration artifacts.',
-    'Send with sessions send <session-id> --message-file followup.txt --json. Default send does not interrupt. Use --delivery queue or replace-current only when intended. start/send return clientMessageId and the existing accepted/queued result. A queued result may refer to the currently active Run: associate queueItemId/clientMessageId with history before deciding that input finished.',
-    'Wait with sessions wait <session-id> --run <run-id> --timeout 30s --json. This observes that exact Run through the existing Watch. Timeout or cancelled waiting does not stop the task. Use sessions stop <session-id> --run <run-id> --json to stop an explicit active Run; ownership rules still apply.',
+    'Create workers only as tasks need them, named fixer#<task-id> <description> or reviewer#<task-or-change-id> <description>. These are conventions, not product roles or a fixed pool. Put role, scope, acceptance criteria and delivery requirements in the first message. Session Prompt is edited in the Web UI only; marctl has no editing command, and sends to existing Sessions use normal prompt injection.',
+    'Reuse recorded Session/Run IDs and receipts. Refresh volatile Run, queue and Goal state with sessions show only when the next action depends on it. For results use sessions history <session-id> --limit 10 --json; follow nextCursor only for missing evidence. Select needed JSON fields and relevant assistant results instead of dumping full Session lists or tool transcripts. Hidden reasoning, credentials and raw model requests are not collaboration artifacts.',
+    'Send with sessions send <session-id> -m "Review the updated patch" --json. Default send does not interrupt and can resume a paused queue; --delivery queue preserves a paused queue. Otherwise eligible queued input can start when idle. --delivery replace-current cancels the current Run and prioritizes the new input after release; it is not live steering. There are no queue-item edit/delete/reorder commands; show includes queue state. start/send return clientMessageId and the accepted/queued result. A queued result may refer to the currently active Run: associate queueItemId/clientMessageId with history before deciding that input finished.',
+    'Wait with sessions wait <session-id> --run <run-id> --timeout 5m --json through the existing Watch. Prefer --timeout 5m when blocked on task completion; use 30s for a short deadline. Continue useful independent work before waiting. If exec returns a running process or cell, reuse its process/cell handle rather than starting another wait or polling show/list. Timeout or cancelled waiting does not stop the task. Use sessions stop <session-id> --run <run-id> --json only to stop that active Run; ownership rules still apply.',
     'Goal get/set/clear use the existing Session Goal semantics; see marctl help sessions. A Coordinator can work from ordinary messages or its existing schedule without a Goal. Worker completion never automatically wakes it. Actively wait/read results, or finish and reconcile on the next user message or scheduled input.',
     '## Verify, recover and respect authorization',
     'An accepted message or SUCCEEDED Run is not proof of business completion. Inspect artifacts and test evidence. If review finds a defect, send a focused correction to the recorded Fixer Session, then request another review with the recorded Reviewer ID.',

package/dist/runtime-state.js

@@ -78,6 +78,7 @@ export class NodeRuntimeState {
             effort: input.effort ?? null,
             access: input.access ?? null,
             customTitle,
+            sessionPrompt: input.sessionPrompt ?? null,
             runnerTitle: input.title?.trim().slice(0, 160) || null,
             pinnedAt: null,
             // A first user prompt is only a process-local temporary title. A
@@ -112,6 +113,7 @@ export class NodeRuntimeState {
                 effort: null,
                 access: null,
                 customTitle: null,
+                sessionPrompt: null,
                 runnerTitle: null,
                 pinnedAt: null,
                 titleSource: 'AUTO',
@@ -275,6 +277,7 @@ export class NodeRuntimeState {
             throw new Error('SESSION_TITLE_INVALID');
         return this.replaceSession(current.id, {
             customTitle: title,
+            sessionPrompt: input.sessionPrompt === undefined ? (current.sessionPrompt ?? null) : input.sessionPrompt,
             pinnedAt: input.pinned === undefined ? current.pinnedAt : input.pinned ? this.now() : null,
             titleSource: title === null ? 'AUTO' : 'CUSTOM'
         });

package/dist/service/continuous-run-coordinator.js

@@ -1,5 +1,6 @@
 import { withNonImageAttachmentPrompt } from '../util/node-operation-parsers.js';
 import { safeErrorCode } from '../util/safe-error.js';
+import { withSessionPrompt } from '../util/personal-instructions.js';
 import { prepareComposerResourceInput } from './composer-message-input.js';
 export class ContinuousRunCoordinator {
     options;
@@ -327,6 +328,7 @@ export class ContinuousRunCoordinator {
                 this.rejectStaleGoal(executionId);
                 return;
             }
+            const personalInstructions = withSessionPrompt(pending.personalInstructions, this.options.runtime.getAgentSession(pending.sessionId)?.sessionPrompt);
             this.options.control('run.start', {
                 ...(pending.usageGrant === undefined ? {} : { usageGrant: pending.usageGrant }),
                 runId: executionId,
@@ -364,9 +366,7 @@ export class ContinuousRunCoordinator {
                             ...mailMcp?.secrets
                         }
                     }),
-                ...(pending.personalInstructions === undefined
-                    ? {}
-                    : { personalInstructions: pending.personalInstructions }),
+                ...(personalInstructions === undefined ? {} : { personalInstructions }),
                 ...(pending.marAgentModel === undefined ? {} : { marAgentModel: pending.marAgentModel }),
                 ...(pending.marAgentModels === undefined ? {} : { marAgentModels: pending.marAgentModels }),
                 ...(pending.marAgentCompact === undefined

package/dist/service/external-session-resume-service.js

@@ -69,7 +69,8 @@ export class ExternalSessionResumeService {
                         effort: configuration.effort,
                         access: configuration.access,
                         ...(session.runnerTitle === null ? {} : { title: session.runnerTitle }),
-                        ...(session.customTitle === null ? {} : { customTitle: session.customTitle })
+                        ...(session.customTitle === null ? {} : { customTitle: session.customTitle }),
+                        sessionPrompt: session.sessionPrompt ?? null
                     });
                 },
                 workspacePath: this.options.workspacePath,

package/dist/service/native-session-projection-service.js

@@ -80,6 +80,7 @@ export class NativeSessionProjectionService {
             effort: record.metadata.effort,
             access: record.metadata.access,
             customTitle: record.metadata.customTitle,
+            sessionPrompt: record.metadata.sessionPrompt ?? null,
             runnerTitle: record.metadata.runnerTitle,
             pinnedAt: record.pinOrder === null ? null : 1,
             pinOrder: record.pinOrder,
@@ -112,7 +113,8 @@ export class NativeSessionProjectionService {
             ...(direct.effort === null ? {} : { effort: direct.effort }),
             ...(direct.access === null ? {} : { access: direct.access }),
             ...(direct.runnerTitle === null ? {} : { title: direct.runnerTitle }),
-            ...(direct.customTitle === null ? {} : { customTitle: direct.customTitle })
+            ...(direct.customTitle === null ? {} : { customTitle: direct.customTitle }),
+            sessionPrompt: direct.sessionPrompt ?? null
         });
     }
     resumedConfiguration(session) {
@@ -183,6 +185,7 @@ export class NativeSessionProjectionService {
             effort: metadata?.effort ?? null,
             access: metadata?.access ?? null,
             customTitle: metadata?.customTitle ?? null,
+            sessionPrompt: metadata?.sessionPrompt ?? null,
             runnerTitle,
             pinnedAt: metadata?.pinnedAt ?? null,
             pinOrder: metadata?.pinOrder ?? null,

package/dist/service/session-catalog-service.js

@@ -94,6 +94,7 @@ export class SessionCatalogService {
                 effort: persisted.metadata.effort,
                 access: persisted.metadata.access,
                 customTitle: persisted.metadata.customTitle,
+                sessionPrompt: persisted.metadata.sessionPrompt ?? null,
                 runnerTitle: persisted.metadata.runnerTitle,
                 pinnedAt: persisted.pinOrder === null ? null : 1,
                 pinOrder: persisted.pinOrder,

package/dist/service/session-lifecycle-service.js

@@ -2,6 +2,7 @@ import { parseMessageAttachments, validSessionEffort, validSessionOption, validS
 import { isPlainRecord } from '../util/node-operation-parsers.js';
 import { parseSecretEnvironment } from '../util/secret-environment.js';
 import { ScheduledSessionStore } from './scheduled-session-store.js';
+import { normalizeSessionPrompt } from '../util/personal-instructions.js';
 export class SessionLifecycleService {
     options;
     starts = new Map();
@@ -21,6 +22,7 @@ export class SessionLifecycleService {
         this.starts.clear();
     }
     async updateMetadata(input) {
+        const sessionPrompt = input.sessionPrompt === undefined ? undefined : normalizeSessionPrompt(input.sessionPrompt);
         if (typeof input.sessionId !== 'string' ||
             (input.customTitle !== undefined &&
                 input.customTitle !== null &&
@@ -35,6 +37,8 @@ export class SessionLifecycleService {
             (await this.options.projection.createMetadataProjection(input.sessionId));
         if (current === undefined)
             throw new Error('SESSION_NOT_FOUND');
+        if (sessionPrompt !== undefined && current.externalSessionId === null)
+            throw new Error('SESSION_ACTIVATION_REQUIRED');
         if (input.pinned === false) {
             const task = new ScheduledSessionStore(this.options.database().raw).get(current.externalSessionId ?? current.id);
             if (task?.enabled === true)
@@ -43,21 +47,31 @@ export class SessionLifecycleService {
         const nativeCodexRename = this.options.runners.require(current.runner).usesRunnerTitleForRename() &&
             current.externalSessionId !== null &&
             input.customTitle !== undefined;
-        await this.options.projection.rename(current, {
-            ...(input.customTitle === undefined ? {} : { title: input.customTitle }),
-            ...(input.pinned === undefined ? {} : { pinned: input.pinned })
-        });
+        if (input.customTitle !== undefined || input.pinned !== undefined)
+            await this.options.projection.rename(current, {
+                ...(input.customTitle === undefined ? {} : { title: input.customTitle }),
+                ...(input.pinned === undefined ? {} : { pinned: input.pinned })
+            });
+        if (sessionPrompt !== undefined && current.externalSessionId !== null)
+            this.options.database().saveNativeSessionMetadata({
+                runner: current.runner,
+                externalSessionId: current.externalSessionId,
+                workspaceId: current.workspaceId,
+                sessionPrompt
+            });
         const metadataTitle = nativeCodexRename ? null : input.customTitle;
         const updated = this.options.runtime.updateSessionMetadata({
             sessionId: current.id,
+            ...(sessionPrompt === undefined ? {} : { sessionPrompt }),
             ...(metadataTitle === undefined ? {} : { customTitle: metadataTitle }),
             ...(input.pinned === undefined ? {} : { pinned: input.pinned })
         });
-        return {
-            session: this.options.present(nativeCodexRename
-                ? this.options.runtime.setRunnerTitleFromNative(updated.id, input.customTitle ?? '')
-                : updated)
-        };
+        const next = nativeCodexRename
+            ? this.options.runtime.setRunnerTitleFromNative(updated.id, input.customTitle ?? '')
+            : updated;
+        if (sessionPrompt !== undefined)
+            this.options.emitSession(next);
+        return { session: this.options.present(next) };
     }
     movePin(input) {
         if (typeof input.sessionId !== 'string' ||

package/dist/service/session-presentation-service.js

@@ -9,7 +9,12 @@ export class SessionPresentationService {
         if (session.externalSessionId !== null && database !== undefined) {
             const metadata = database.getNativeSessionMetadata(session.runner, session.externalSessionId, session.workspaceId);
             if (metadata !== undefined)
-                session = { ...session, pinnedAt: metadata.pinnedAt, pinOrder: metadata.pinOrder };
+                session = {
+                    ...session,
+                    sessionPrompt: metadata.sessionPrompt ?? null,
+                    pinnedAt: metadata.pinnedAt,
+                    pinOrder: metadata.pinOrder
+                };
         }
         const presentation = this.options.runners
             .require(session.runner)
@@ -23,7 +28,7 @@ export class SessionPresentationService {
             runtime: {
                 ...presentation.runtime,
                 capabilities: session.externalSessionId !== null && database !== undefined
-                    ? [...presentation.runtime.capabilities, 'session.schedule']
+                    ? [...presentation.runtime.capabilities, 'session.schedule', 'session.prompt']
                     : presentation.runtime.capabilities
             },
             schedule: database === undefined

package/dist/util/personal-instructions.js

@@ -1,4 +1,15 @@
 const MAX_CONTENT_LENGTH = 20_000;
+export function normalizeSessionPrompt(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || value.trim().length > MAX_CONTENT_LENGTH)
+        throw new Error('SESSION_PROMPT_INVALID');
+    return value.trim() || null;
+}
+export function withSessionPrompt(personalInstructions, sessionPrompt) {
+    const merged = [personalInstructions, sessionPrompt].filter(Boolean).join('\n\n');
+    return merged.length === 0 ? undefined : merged;
+}
 export function personalInstructionsForRunner(value, runner) {
     if (value === undefined)
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.10.32",
+  "version": "0.10.33",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -37,10 +37,10 @@
     "playwright": "1.62.1",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.10.32",
-    "@myagentroam/code-navigation": "0.10.1",
-    "@myagentroam/marctl": "0.10.4",
-    "@myagentroam/protocol": "0.10.32"
+    "@myagentroam/agent": "0.10.33",
+    "@myagentroam/protocol": "0.10.33",
+    "@myagentroam/marctl": "0.10.5",
+    "@myagentroam/code-navigation": "0.10.1"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"