@jhytabest/plashboard 1.0.0 → 1.0.1

package/README.md

@@ -25,6 +25,7 @@ No manual config is required for first use. Defaults are safe:
 - `fill_provider=openclaw`
 - `allow_command_fill=false`
 - `openclaw_fill_agent_id=main`
+- `session_strategy=persistent`
 - automatic init on service start
 - automatic starter template seed when template store is empty
 
@@ -58,6 +59,7 @@ Add to `openclaw.json`:
           "fill_provider": "openclaw",
           "allow_command_fill": false,
           "openclaw_fill_agent_id": "main",
+          "session_strategy": "persistent",
           "display_profile": {
             "width_px": 1920,
             "height_px": 1080,
@@ -77,6 +79,33 @@ Add to `openclaw.json`:
 `fill_provider: "command"` requires explicit opt-in with `allow_command_fill: true`.
 Use command mode only if you need a custom external runner.
 
+`session_strategy` controls OpenClaw session reuse for fills:
+- `persistent` (default): reuses the agent's normal long-lived session behavior.
+- `ephemeral`: each fill run gets a unique `--session-id`; after the run, plugin performs best-effort cleanup via official CLI API: `openclaw sessions delete --agent <id> --session-id <id>`.
+
+Tradeoffs:
+- `persistent` keeps conversational memory/context between runs.
+- `ephemeral` isolates runs and avoids long-lived context drift, but loses cross-run memory and adds one cleanup CLI call per run.
+
+Example ephemeral config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "plashboard": {
+        "enabled": true,
+        "config": {
+          "fill_provider": "openclaw",
+          "openclaw_fill_agent_id": "plashboard-fill",
+          "session_strategy": "ephemeral"
+        }
+      }
+    }
+  }
+}
+```
+
 For production stability, use a dedicated fill agent instead of `main`:
 
 ```bash

package/openclaw.plugin.json

@@ -20,6 +20,7 @@
       "allow_command_fill": { "type": "boolean", "default": false },
       "fill_command": { "type": "string" },
       "openclaw_fill_agent_id": { "type": "string", "default": "main" },
+      "session_strategy": { "type": "string", "enum": ["persistent", "ephemeral"], "default": "persistent" },
       "python_bin": { "type": "string", "default": "python3" },
       "writer_script_path": { "type": "string" },
       "dashboard_output_path": { "type": "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhytabest/plashboard",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Plashboard OpenClaw plugin runtime",
   "license": "MIT",

package/src/config.ts

@@ -38,6 +38,10 @@ function asObject(value: unknown): Record<string, unknown> {
     : {};
 }
 
+function asSessionStrategy(value: unknown): PlashboardConfig['session_strategy'] {
+  return value === 'ephemeral' ? 'ephemeral' : 'persistent';
+}
+
 function resolveDisplayProfile(raw: unknown): DisplayProfile {
   const data = asObject(raw);
   return {
@@ -80,6 +84,7 @@ export function resolveConfig(api: unknown): PlashboardConfig {
     allow_command_fill: asBoolean(raw.allow_command_fill, false),
     fill_command: typeof raw.fill_command === 'string' ? raw.fill_command : undefined,
     openclaw_fill_agent_id: asString(raw.openclaw_fill_agent_id, 'main'),
+    session_strategy: asSessionStrategy(raw.session_strategy),
     python_bin: asString(raw.python_bin, 'python3'),
     writer_script_path: asString(raw.writer_script_path, DEFAULT_WRITER_PATH),
     dashboard_output_path: outputPath,

package/src/fill-runner.test.ts

@@ -42,6 +42,7 @@ function config(overrides: Partial<PlashboardConfig>): PlashboardConfig {
     allow_command_fill: false,
     fill_command: undefined,
     openclaw_fill_agent_id: 'main',
+    session_strategy: 'persistent',
     python_bin: 'python3',
     writer_script_path: '/tmp/writer.py',
     dashboard_output_path: '/tmp/dashboard.json',
@@ -68,7 +69,7 @@ function context(): FillRunContext {
 }
 
 describe('createFillRunner', () => {
-  it('parses openclaw json envelope output', async () => {
+  it('persistent mode keeps standard openclaw agent session behavior', async () => {
     const commandRunner = vi.fn(async (_argv: string[], _options: unknown) => ({
       stdout: JSON.stringify({
         result: {
@@ -96,6 +97,108 @@ describe('createFillRunner', () => {
     expect(argv.slice(0, 2)).toEqual(['openclaw', 'agent']);
     expect(argv).toContain('--agent');
     expect(argv).toContain('ops');
+    expect(argv).not.toContain('--session-id');
+  });
+
+  it('ephemeral mode uses unique session ids and official cleanup command', async () => {
+    const calls: string[][] = [];
+    const commandRunner = vi.fn(async (argv: string[], _options: unknown) => {
+      calls.push(argv);
+      if (argv[0] === 'openclaw' && argv[1] === 'agent') {
+        return {
+          stdout: '{"values":{"summary":"new summary"}}',
+          stderr: '',
+          code: 0
+        };
+      }
+      if (argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete') {
+        return {
+          stdout: '{"ok":true}',
+          stderr: '',
+          code: 0
+        };
+      }
+      return {
+        stdout: '',
+        stderr: `unsupported command: ${argv.join(' ')}`,
+        code: 1
+      };
+    });
+
+    const runner = createFillRunner(
+      config({
+        fill_provider: 'openclaw',
+        openclaw_fill_agent_id: 'ops',
+        session_strategy: 'ephemeral'
+      }),
+      { commandRunner }
+    );
+
+    await runner.run(context());
+    await runner.run(context());
+
+    const agentCalls = calls.filter((argv) => argv[0] === 'openclaw' && argv[1] === 'agent');
+    const cleanupCalls = calls.filter((argv) => argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete');
+
+    expect(agentCalls).toHaveLength(2);
+    expect(cleanupCalls).toHaveLength(2);
+
+    const firstSessionFlagIndex = agentCalls[0].indexOf('--session-id');
+    const secondSessionFlagIndex = agentCalls[1].indexOf('--session-id');
+    expect(firstSessionFlagIndex).toBeGreaterThan(-1);
+    expect(secondSessionFlagIndex).toBeGreaterThan(-1);
+    const firstSessionId = agentCalls[0][firstSessionFlagIndex + 1];
+    const secondSessionId = agentCalls[1][secondSessionFlagIndex + 1];
+    expect(firstSessionId).toBeTruthy();
+    expect(secondSessionId).toBeTruthy();
+    expect(firstSessionId).not.toBe(secondSessionId);
+
+    for (const [index, cleanupCall] of cleanupCalls.entries()) {
+      expect(cleanupCall.slice(0, 3)).toEqual(['openclaw', 'sessions', 'delete']);
+      expect(cleanupCall).toContain('--agent');
+      expect(cleanupCall).toContain('ops');
+      const cleanupSessionFlagIndex = cleanupCall.indexOf('--session-id');
+      expect(cleanupSessionFlagIndex).toBeGreaterThan(-1);
+      expect(cleanupCall[cleanupSessionFlagIndex + 1]).toBe(index === 0 ? firstSessionId : secondSessionId);
+    }
+  });
+
+  it('ephemeral cleanup failure is safe and does not fail fill output', async () => {
+    const commandRunner = vi.fn(async (argv: string[], _options: unknown) => {
+      if (argv[0] === 'openclaw' && argv[1] === 'agent') {
+        return {
+          stdout: '{"values":{"summary":"new summary"}}',
+          stderr: '',
+          code: 0
+        };
+      }
+      if (argv[0] === 'openclaw' && argv[1] === 'sessions' && argv[2] === 'delete') {
+        return {
+          stdout: '',
+          stderr: 'session cleanup failed',
+          code: 1
+        };
+      }
+      return {
+        stdout: '',
+        stderr: `unsupported command: ${argv.join(' ')}`,
+        code: 1
+      };
+    });
+
+    const runner = createFillRunner(
+      config({
+        fill_provider: 'openclaw',
+        openclaw_fill_agent_id: 'ops',
+        session_strategy: 'ephemeral'
+      }),
+      { commandRunner }
+    );
+    const response = await runner.run(context());
+
+    expect(response.values.summary).toBe('new summary');
+    expect(commandRunner).toHaveBeenCalledTimes(2);
+    expect(commandRunner.mock.calls[1][0].slice(0, 3)).toEqual(['openclaw', 'sessions', 'delete']);
   });
 
   it('parses command runner fenced json output', async () => {

package/src/fill-runner.ts

@@ -1,10 +1,12 @@
-import { runAndReadStdout, type CommandRunner } from './command-runner.js';
+import { runAndReadStdout, runCommand, type CommandRunner } from './command-runner.js';
 import type { FillResponse, FillRunContext, FillRunner, PlashboardConfig } from './types.js';
 
 export interface FillRunnerDeps {
   commandRunner?: CommandRunner | null;
 }
 
+let ephemeralSessionCounter = 0;
+
 function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
   return {
     instructions: {
@@ -142,6 +144,25 @@ function parseFillResponse(output: string, source: string): FillResponse {
   return extracted;
 }
 
+function sanitizeSessionToken(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'x';
+}
+
+function nextEphemeralSessionCounter(): number {
+  ephemeralSessionCounter += 1;
+  return ephemeralSessionCounter;
+}
+
+function buildEphemeralSessionId(agentId: string, context: FillRunContext): string {
+  const templateId = sanitizeSessionToken(context.template.id || 'template');
+  const agent = sanitizeSessionToken(agentId || 'agent');
+  const attempt = Math.max(1, Math.floor(context.attempt || 1));
+  const now = Date.now().toString(36);
+  const pid = process.pid.toString(36);
+  const seq = nextEphemeralSessionCounter().toString(36);
+  return `plash-${agent}-${templateId}-a${attempt}-${pid}-${now}-${seq}`;
+}
+
 class MockFillRunner implements FillRunner {
   async run(context: FillRunContext): Promise<FillResponse> {
     const values: Record<string, unknown> = {};
@@ -192,17 +213,37 @@ class OpenClawFillRunner implements FillRunner {
     const agentId = (this.config.openclaw_fill_agent_id || 'main').trim() || 'main';
     const timeoutSeconds = Math.max(10, Math.floor(this.config.session_timeout_seconds));
     const message = buildOpenClawMessage(context);
+    const ephemeral = this.config.session_strategy === 'ephemeral';
+    const sessionId = ephemeral ? buildEphemeralSessionId(agentId, context) : undefined;
+    const argv = ['openclaw', 'agent', '--agent', agentId, '--message', message, '--json', '--timeout', String(timeoutSeconds)];
+    if (sessionId) {
+      argv.push('--session-id', sessionId);
+    }
 
-    const output = await runAndReadStdout(
-      this.commandRunner,
-      ['openclaw', 'agent', '--agent', agentId, '--message', message, '--json', '--timeout', String(timeoutSeconds)],
-      {
-        timeoutMs: (timeoutSeconds + 30) * 1000
-      },
-      'openclaw fill'
-    );
+    try {
+      const output = await runAndReadStdout(
+        this.commandRunner,
+        argv,
+        {
+          timeoutMs: (timeoutSeconds + 30) * 1000
+        },
+        'openclaw fill'
+      );
 
-    return parseFillResponse(output, 'openclaw fill');
+      return parseFillResponse(output, 'openclaw fill');
+    } finally {
+      if (ephemeral && sessionId) {
+        // Best-effort cleanup through official CLI API; never mutate session files directly.
+        await runCommand(
+          this.commandRunner,
+          ['openclaw', 'sessions', 'delete', '--agent', agentId, '--session-id', sessionId, '--json'],
+          {
+            timeoutMs: Math.max(5, timeoutSeconds) * 1000
+          },
+          'openclaw ephemeral session cleanup'
+        );
+      }
+    }
   }
 }
 

package/src/plugin.ts

@@ -80,6 +80,7 @@ type SetupParams = {
   allow_command_fill?: boolean;
   fill_command?: string;
   openclaw_fill_agent_id?: string;
+  session_strategy?: 'persistent' | 'ephemeral';
   auto_seed_template?: boolean;
   data_dir?: string;
   scheduler_tick_seconds?: number;
@@ -514,6 +515,10 @@ async function runSetup(
     || asString(resolvedConfig.openclaw_fill_agent_id)
     || 'main'
   ).trim();
+  const rawSessionStrategy = asString(params.session_strategy)
+    || asString(currentPluginConfig.session_strategy)
+    || asString(resolvedConfig.session_strategy);
+  const selectedSessionStrategy = rawSessionStrategy === 'ephemeral' ? 'ephemeral' : 'persistent';
 
   if (selectedProvider === 'command' && !selectedCommand) {
     return {
@@ -587,6 +592,7 @@ async function runSetup(
     ),
     fill_provider: selectedProvider,
     allow_command_fill: selectedAllowCommandFill,
+    session_strategy: selectedSessionStrategy,
     auto_seed_template: selectedAutoSeed,
     display_profile: displayProfile
   };
@@ -630,6 +636,7 @@ async function runSetup(
       allow_command_fill: selectedAllowCommandFill,
       fill_command: selectedProvider === 'command' ? selectedCommand : undefined,
       openclaw_fill_agent_id: selectedProvider === 'openclaw' ? selectedAgentId : undefined,
+      session_strategy: selectedSessionStrategy,
       auto_seed_template: selectedAutoSeed,
       data_dir: nextPluginConfig.data_dir,
       scheduler_tick_seconds: nextPluginConfig.scheduler_tick_seconds,
@@ -1064,6 +1071,7 @@ export function registerPlashboardPlugin(api: UnknownApi): void {
         allow_command_fill: { type: 'boolean' },
         fill_command: { type: 'string' },
         openclaw_fill_agent_id: { type: 'string' },
+        session_strategy: { type: 'string', enum: ['persistent', 'ephemeral'] },
         auto_seed_template: { type: 'boolean' },
         data_dir: { type: 'string' },
         scheduler_tick_seconds: { type: 'number' },

package/src/runtime.test.ts

@@ -66,6 +66,7 @@ async function setupRuntime(overrides: Partial<PlashboardConfig> = {}) {
     fill_provider: 'mock',
     allow_command_fill: false,
     fill_command: undefined,
+    session_strategy: 'persistent',
     python_bin: 'python3',
     writer_script_path: join(process.cwd(), 'scripts', 'dashboard_write.py'),
     dashboard_output_path: join(root, 'dashboard.json'),

package/src/types.ts

@@ -15,6 +15,8 @@ export interface ModelDefaults {
   max_tokens?: number;
 }
 
+export type SessionStrategy = 'persistent' | 'ephemeral';
+
 export interface PlashboardConfig {
   data_dir: string;
   timezone: string;
@@ -28,6 +30,7 @@ export interface PlashboardConfig {
   allow_command_fill: boolean;
   fill_command?: string;
   openclaw_fill_agent_id?: string;
+  session_strategy: SessionStrategy;
   python_bin: string;
   writer_script_path: string;
   dashboard_output_path: string;