@openchambery/web 1.19.20 → 2.0.0-beta.1

package/server/lib/session-goal/DOCUMENTATION.md

@@ -1,10 +1,34 @@
 # Session Goal
 
 Server-side control loop that keeps a session working toward a user-defined
-objective stored under `metadata.openchamber.goal`, with the small model as
-an independent progress auditor. Built on OpenChamber's backend-driven
-architecture: the loop lives in
-the web server and survives UI disconnects.
+objective. On OpenCode 2.x the goal record lives in the OpenChamber session
+metadata store (`packages/web/server/lib/session-metadata/`), folded back onto
+`session.metadata` by the proxy. Capability is **open** (`supported: true`):
+manual UI, goal routes, and scheduled-task goal create all write the same
+store. The small model is an independent progress auditor. Built on
+OpenChamber's backend-driven architecture: the loop lives in the web server
+and survives UI disconnects.
+
+## v2 storage (OpenChamber session metadata store)
+
+OpenCode 2.x accepts session `metadata` only at create time — there is no
+PATCH. Goal progress therefore belongs in the Host
+`packages/web/server/lib/session-metadata/` store (merge-patched under
+`openchamber.goal`), not an OpenCode `PATCH /session/:id`.
+
+`createSessionGoalRuntime` accepts optional seams `readSessionMetadata` and
+`persistSessionGoal`. When **both** are injected, `writeGoal` / goal reads use
+only the store and never PATCH OpenCode. When either is missing, the legacy
+OpenCode PATCH path remains (tests and unwired servers).
+
+Those seams, the proxy overlay, and `PUT /api/openchamber/sessions/:id/metadata`
+are wired in `server/index.js`. A UI metadata write notifies the runtime with
+a synthetic `session.updated` so create/resume can arm the loop.
+
+**Capability is open** (`supported === true`). Scheduled-task goal create and
+`POST /api/goals/:sessionId` persist an active goal into the same store as
+manual UI metadata writes; after first persist they notify the runtime with a
+synthetic `session.updated` so the loop can arm.
 
 ## Goal payload (`metadata.openchamber.goal`)
 
@@ -53,11 +77,16 @@ before touching the filesystem). Rationale: metadata rides every
 `session.updated`, so multi-KB objectives must not live there.
 
 - `objectives.js` — write/read/delete, 5000-char clamp.
-- `routes.js` — `PUT/GET/DELETE /api/goals/objective/:sessionId`
-  (OpenChamber-owned, registered before the generic proxy; JSON parsing via
-  the `/api/goals` family in core-routes). The UI writes the file BEFORE
-  patching the goal metadata and falls back to an inline objective when the
-  write fails; `clearSessionGoal` deletes the file best-effort.
+- `capability.js` — `getSessionGoalCapability()` / `assertSessionGoalSupported()`
+  (single source; currently `{ supported: true }`).
+- `routes.js` — `GET /api/goals/capability`, create/resume endpoints,
+  `PUT/GET/DELETE /api/goals/objective/:sessionId` (OpenChamber-owned,
+  registered before the generic proxy; JSON parsing via the `/api/goals`
+  family in core-routes). Create / resume require an injected
+  `persistSessionGoal` (503 when missing); objective PUT writes the file when
+  supported. The UI writes the file BEFORE patching the goal metadata and
+  falls back to an inline objective when the write fails;
+  `clearSessionGoal` deletes the file best-effort.
 - The tick resolves the effective objective fresh on every cycle (the file
   is live-editable mid-goal) and falls back to the inline `objective` when
   the file is unreadable — a goal never dies because a file went away.
@@ -183,13 +212,35 @@ sees only that final turn, so the report is its evidence.
   (edit/pause/resume/complete/clear).
 - Sidebar glyph next to the date in `SessionNodeItem`.
 
+## Capability (Host goal state)
+
+`capability.js` is the single source for whether Host goal state is available:
+
+```
+getSessionGoalCapability() → { supported: true }
+```
+
+Goal records live in the OpenChamber session-metadata store (not OpenCode
+SessionInfo). Routes, scheduled tasks, and the proxy overlay share that store.
+
+| Surface | While supported |
+|---|---|
+| `GET /api/goals/capability` | `{ supported: true }` |
+| `POST /api/goals/:sessionId` (create) | Write objective + persist active goal (503 if persist missing) |
+| `POST /api/goals/:sessionId/resume` | Set status active / statusReason resumed (404 if no goal) |
+| `PUT /api/goals/objective/:sessionId` | Writes the objective file |
+| `GET` / `DELETE` objective | Allowed |
+| Scheduled `goalEnabled` create/edit | Allowed |
+| Existing `goalEnabled` task run | Persist goal after session create; fail before create if persist unwired |
+
 ## Scheduled goals
 
-Scheduled tasks can run as goals: `execution.goalEnabled` (+ optional
-`execution.goalTokenBudget`) on a task makes the scheduled-tasks runtime
-stamp `metadata.openchamber.goal` onto the fresh session (objective = the
-expanded task prompt) and attach the goal-mode intro part to the prompt.
-The loop here picks it up from session events like any other goal.
+Scheduled tasks with `execution.goalEnabled` (+ optional
+`execution.goalTokenBudget`) write the objective file, persist an active goal
+into the Host store (same shape as manual create), notify the goal runtime to
+arm, and attach the goal-mode intro to the prompt. Without
+`persistSessionGoal` injected, runs fail **before** session create (no
+create/distill/prompt side effects).
 
 ## Limitations
 

package/server/lib/session-goal/capability.js

@@ -0,0 +1,57 @@
+/**
+ * Session-goal Host capability for the current OpenCode surface.
+ *
+ * Goal records live in the OpenChamber session-metadata store
+ * (`packages/web/server/lib/session-metadata/`), not OpenCode SessionInfo.
+ * When the store + scheduled-task / route persist seams are wired, advertise
+ * supported so create·resume·edit paths write trackable goal state.
+ *
+ * `SESSION_GOAL_UNSUPPORTED_REASON` remains for structured refusals if a
+ * future surface must advertise unsupported again.
+ */
+
+export const SESSION_GOAL_UNSUPPORTED_REASON = 'v2_goal_state_unavailable';
+
+/**
+ * @returns {{ supported: false, reason: typeof SESSION_GOAL_UNSUPPORTED_REASON }
+ *   | { supported: true, reason?: undefined }}
+ */
+export function getSessionGoalCapability() {
+  return {
+    supported: true,
+  };
+}
+
+export function isSessionGoalSupported() {
+  return getSessionGoalCapability().supported === true;
+}
+
+/**
+ * Human-readable refusal for APIs / run history when goal state is unavailable.
+ * @param {{ supported: boolean, reason?: string }} [capability]
+ */
+export function sessionGoalUnavailableMessage(capability = getSessionGoalCapability()) {
+  const reason = typeof capability?.reason === 'string' && capability.reason.trim()
+    ? capability.reason.trim()
+    : SESSION_GOAL_UNSUPPORTED_REASON;
+  return `session goal is unavailable (${reason})`;
+}
+
+/**
+ * Throw a structured refusal for create / edit / resume / objective-write paths.
+ * @param {{ operation?: string }} [options]
+ */
+export function assertSessionGoalSupported(options = {}) {
+  const capability = getSessionGoalCapability();
+  if (capability.supported) {
+    return capability;
+  }
+  const operation = typeof options.operation === 'string' && options.operation.trim()
+    ? options.operation.trim()
+    : 'goal';
+  const error = new Error(`${sessionGoalUnavailableMessage(capability)}: cannot ${operation}`);
+  error.statusCode = 501;
+  error.code = capability.reason || SESSION_GOAL_UNSUPPORTED_REASON;
+  error.capability = capability;
+  throw error;
+}

package/server/lib/session-goal/capability.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  SESSION_GOAL_UNSUPPORTED_REASON,
+  assertSessionGoalSupported,
+  getSessionGoalCapability,
+  isSessionGoalSupported,
+  sessionGoalUnavailableMessage,
+} from './capability.js';
+
+describe('session-goal capability', () => {
+  it('advertises supported Host goal state (session-metadata store)', () => {
+    expect(getSessionGoalCapability()).toEqual({
+      supported: true,
+    });
+    expect(SESSION_GOAL_UNSUPPORTED_REASON).toBe('v2_goal_state_unavailable');
+    expect(isSessionGoalSupported()).toBe(true);
+  });
+
+  it('formats a stable unavailable message for run history and APIs', () => {
+    expect(sessionGoalUnavailableMessage({
+      supported: false,
+      reason: SESSION_GOAL_UNSUPPORTED_REASON,
+    })).toBe(
+      'session goal is unavailable (v2_goal_state_unavailable)',
+    );
+  });
+
+  it('assertSessionGoalSupported returns when supported', () => {
+    expect(assertSessionGoalSupported({ operation: 'create' })).toEqual({
+      supported: true,
+    });
+  });
+});

package/server/lib/session-goal/routes.js

@@ -1,12 +1,234 @@
+import crypto from 'node:crypto';
+import {
+  assertSessionGoalSupported,
+  getSessionGoalCapability,
+  isSessionGoalSupported,
+  sessionGoalUnavailableMessage,
+} from './capability.js';
 import { deleteObjective, readObjective, writeObjective } from './objectives.js';
 
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const refuseGoalMutation = (res, operation) => {
+  try {
+    assertSessionGoalSupported({ operation });
+    return false;
+  } catch (error) {
+    const capability = error?.capability || getSessionGoalCapability();
+    res.status(Number(error?.statusCode) || 501).json({
+      error: error?.message || sessionGoalUnavailableMessage(capability),
+      reason: capability.reason,
+      capability,
+      operation,
+    });
+    return true;
+  }
+};
+
+const resolveTokenBudget = (value) => {
+  if (Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return null;
+};
+
+/**
+ * Build an active goal record accepted by parseGoalMetadata.
+ * File-backed: objectiveFile true (objective may be empty).
+ * Inline fallback: objective text required.
+ */
+const buildActiveGoalRecord = ({
+  objective = '',
+  objectiveFile = false,
+  tokenBudget = null,
+  statusReason = '',
+  id = null,
+} = {}) => {
+  const now = Date.now();
+  const inline = typeof objective === 'string' ? objective.trim() : '';
+  return {
+    id: typeof id === 'string' && id ? id : crypto.randomUUID(),
+    status: 'active',
+    objective: objectiveFile ? '' : inline,
+    objectiveFile: objectiveFile === true,
+    tokenBudget: resolveTokenBudget(tokenBudget),
+    tokensUsed: 0,
+    turnsUsed: 0,
+    blockedStreak: 0,
+    note: '',
+    statusReason: typeof statusReason === 'string' ? statusReason : '',
+    lastAccountedMessageID: '',
+    createdAt: now,
+    updatedAt: now,
+  };
+};
+
 // OpenChamber-owned routes for file-backed goal objectives, keyed by session
 // id (one goal per session; a new goal overwrites the old file). The UI
 // writes the objective file before stamping the goal metadata (which only
 // carries an `objectiveFile: true` flag), reads it back for display, and
 // deletes it when the goal is removed.
-export function registerSessionGoalRoutes(app) {
+//
+// Host goal state lives in the session-metadata store. Create / resume need
+// an injected persistSessionGoal; without it they return 503 rather than
+// pretending success. GET remains readable for leftover files.
+export function registerSessionGoalRoutes(app, deps = {}) {
+  const {
+    persistSessionGoal = null,
+    readSessionMetadata = null,
+    /** After create/resume persist — arm the goal loop (synthetic session.updated). */
+    onGoalPersisted = null,
+  } = deps;
+
+  const notifyGoalPersisted = (sessionID, directory, persisted, goal) => {
+    if (typeof onGoalPersisted !== 'function') return;
+    try {
+      const metadata = persisted
+        && typeof persisted === 'object'
+        && !Array.isArray(persisted)
+        && persisted.openchamber
+        ? persisted
+        : { openchamber: { goal } };
+      onGoalPersisted({ sessionID, directory: directory || '', metadata });
+    } catch (error) {
+      console.warn('[session-goal] onGoalPersisted failed:', error?.message || error);
+    }
+  };
+
+  app.get('/api/goals/capability', (_req, res) => {
+    res.json(getSessionGoalCapability());
+  });
+
+  app.post('/api/goals/:sessionId', async (req, res) => {
+    if (refuseGoalMutation(res, 'create')) return;
+    if (typeof persistSessionGoal !== 'function') {
+      res.status(503).json({
+        error: 'session goal persist is not configured',
+        operation: 'create',
+        capability: getSessionGoalCapability(),
+      });
+      return;
+    }
+
+    const sessionId = asNonEmptyString(req.params?.sessionId);
+    if (!sessionId) {
+      res.status(400).json({ error: 'a session id is required' });
+      return;
+    }
+
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    const directory = asNonEmptyString(body.directory) || '';
+    const objectiveText = typeof body.objective === 'string' ? body.objective : '';
+    const tokenBudget = body.tokenBudget ?? body.goalTokenBudget ?? null;
+
+    let objectiveFile = false;
+    let inlineObjective = objectiveText;
+    try {
+      await writeObjective(sessionId, objectiveText);
+      objectiveFile = true;
+      inlineObjective = '';
+    } catch (error) {
+      console.warn('[session-goal] objective file write failed, using inline objective:', error?.message || error);
+      if (!asNonEmptyString(inlineObjective)) {
+        res.status(400).json({ error: 'objective is required when the objective file cannot be written' });
+        return;
+      }
+    }
+
+    const goal = buildActiveGoalRecord({
+      objective: inlineObjective,
+      objectiveFile,
+      tokenBudget,
+    });
+
+    let persisted;
+    try {
+      persisted = await persistSessionGoal(sessionId, directory, goal);
+    } catch (error) {
+      const message = error?.message || 'Failed to persist session goal';
+      console.error('[session-goal] create persist failed:', message);
+      res.status(500).json({ error: message, operation: 'create' });
+      return;
+    }
+
+    notifyGoalPersisted(sessionId, directory, persisted, goal);
+    res.json({ ok: true, goal });
+  });
+
+  app.post('/api/goals/:sessionId/resume', async (req, res) => {
+    if (refuseGoalMutation(res, 'resume')) return;
+    if (typeof persistSessionGoal !== 'function') {
+      res.status(503).json({
+        error: 'session goal persist is not configured',
+        operation: 'resume',
+        capability: getSessionGoalCapability(),
+      });
+      return;
+    }
+    if (typeof readSessionMetadata !== 'function') {
+      res.status(503).json({
+        error: 'session goal metadata read is not configured',
+        operation: 'resume',
+        capability: getSessionGoalCapability(),
+      });
+      return;
+    }
+
+    const sessionId = asNonEmptyString(req.params?.sessionId);
+    if (!sessionId) {
+      res.status(400).json({ error: 'a session id is required' });
+      return;
+    }
+
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    const directory = asNonEmptyString(body.directory) || '';
+
+    let metadata;
+    try {
+      metadata = await readSessionMetadata(sessionId);
+    } catch (error) {
+      const message = error?.message || 'Failed to read session metadata';
+      console.error('[session-goal] resume read failed:', message);
+      res.status(503).json({ error: message, operation: 'resume' });
+      return;
+    }
+
+    const currentGoal = metadata?.openchamber?.goal;
+    if (!currentGoal || typeof currentGoal !== 'object') {
+      res.status(404).json({ error: 'goal not found', operation: 'resume' });
+      return;
+    }
+
+    const now = Date.now();
+    const goal = {
+      ...currentGoal,
+      status: 'active',
+      statusReason: 'resumed',
+      updatedAt: now,
+    };
+
+    let persisted;
+    try {
+      persisted = await persistSessionGoal(sessionId, directory, goal);
+    } catch (error) {
+      const message = error?.message || 'Failed to persist session goal';
+      console.error('[session-goal] resume persist failed:', message);
+      res.status(500).json({ error: message, operation: 'resume' });
+      return;
+    }
+
+    notifyGoalPersisted(sessionId, directory, persisted, goal);
+    res.json({ ok: true, goal });
+  });
+
   app.put('/api/goals/objective/:sessionId', async (req, res) => {
+    // Objective write is part of manual goal create — refuse while unsupported
+    // so create cannot partial-succeed on the file alone.
+    if (refuseGoalMutation(res, 'create')) return;
     try {
       const { content } = req.body || {};
       await writeObjective(req.params.sessionId, content);
@@ -30,7 +252,14 @@ export function registerSessionGoalRoutes(app) {
   });
 
   app.delete('/api/goals/objective/:sessionId', async (req, res) => {
+    // Clear is allowed even when create is unsupported so leftover files from
+    // prior experiments can be removed without implying goal Host support.
     await deleteObjective(req.params.sessionId);
-    res.json({ ok: true });
+    res.json({
+      ok: true,
+      ...(isSessionGoalSupported() ? {} : {
+        capability: getSessionGoalCapability(),
+      }),
+    });
   });
 }

package/server/lib/session-goal/routes.test.js

@@ -0,0 +1,211 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('./objectives.js', () => ({
+  writeObjective: vi.fn(async () => ({ content: 'ok' })),
+  readObjective: vi.fn(async () => 'leftover'),
+  deleteObjective: vi.fn(async () => undefined),
+}));
+
+const { writeObjective, readObjective, deleteObjective } = await import('./objectives.js');
+const { registerSessionGoalRoutes } = await import('./routes.js');
+
+const createRouteRegistry = () => {
+  const routes = new Map();
+  return {
+    app: {
+      get(path, handler) { routes.set(`GET ${path}`, handler); },
+      post(path, handler) { routes.set(`POST ${path}`, handler); },
+      put(path, handler) { routes.set(`PUT ${path}`, handler); },
+      delete(path, handler) { routes.set(`DELETE ${path}`, handler); },
+    },
+    getRoute(method, path) {
+      return routes.get(`${method} ${path}`);
+    },
+  };
+};
+
+const createResponse = () => {
+  let statusCode = 200;
+  let body = null;
+  return {
+    status(code) {
+      statusCode = code;
+      return this;
+    },
+    json(payload) {
+      body = payload;
+      return this;
+    },
+    get statusCode() {
+      return statusCode;
+    },
+    get body() {
+      return body;
+    },
+  };
+};
+
+describe('session-goal routes capability gating', () => {
+  const register = (deps) => {
+    const { app, getRoute } = createRouteRegistry();
+    registerSessionGoalRoutes(app, deps);
+    return getRoute;
+  };
+
+  it('exposes capability as supported', async () => {
+    const getRoute = register();
+    const response = createResponse();
+    await getRoute('GET', '/api/goals/capability')({}, response);
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toEqual({
+      supported: true,
+    });
+  });
+
+  it('returns 503 on create when persist is not injected (no side effects)', async () => {
+    writeObjective.mockClear();
+    const getRoute = register();
+    const response = createResponse();
+    await getRoute('POST', '/api/goals/:sessionId')({
+      params: { sessionId: 'ses_1' },
+      body: { objective: 'ship it' },
+    }, response);
+
+    expect(response.statusCode).toBe(503);
+    expect(response.body.operation).toBe('create');
+    expect(writeObjective).not.toHaveBeenCalled();
+  });
+
+  it('returns 503 on resume when persist is not injected', async () => {
+    const getRoute = register();
+    const response = createResponse();
+    await getRoute('POST', '/api/goals/:sessionId/resume')({
+      params: { sessionId: 'ses_1' },
+    }, response);
+
+    expect(response.statusCode).toBe(503);
+    expect(response.body.operation).toBe('resume');
+  });
+
+  it('writes objective when capability is supported', async () => {
+    writeObjective.mockClear();
+    const getRoute = register();
+    const response = createResponse();
+    await getRoute('PUT', '/api/goals/objective/:sessionId')({
+      params: { sessionId: 'ses_1' },
+      body: { content: 'objective text' },
+    }, response);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toEqual({ ok: true });
+    expect(writeObjective).toHaveBeenCalledWith('ses_1', 'objective text');
+  });
+
+  it('creates an active goal via persist when injected', async () => {
+    writeObjective.mockClear();
+    const persistSessionGoal = vi.fn(async (_id, _dir, goal) => ({
+      openchamber: { goal },
+    }));
+    const onGoalPersisted = vi.fn();
+    const getRoute = register({ persistSessionGoal, onGoalPersisted });
+    const response = createResponse();
+    await getRoute('POST', '/api/goals/:sessionId')({
+      params: { sessionId: 'ses_1' },
+      body: { objective: 'ship it', directory: '/repo', tokenBudget: 5000 },
+    }, response);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.ok).toBe(true);
+    expect(response.body.goal).toMatchObject({
+      status: 'active',
+      objectiveFile: true,
+      objective: '',
+      tokenBudget: 5000,
+      tokensUsed: 0,
+      turnsUsed: 0,
+      blockedStreak: 0,
+    });
+    expect(writeObjective).toHaveBeenCalledWith('ses_1', 'ship it');
+    expect(persistSessionGoal).toHaveBeenCalledTimes(1);
+    expect(persistSessionGoal.mock.calls[0][0]).toBe('ses_1');
+    expect(persistSessionGoal.mock.calls[0][1]).toBe('/repo');
+    expect(onGoalPersisted).toHaveBeenCalledWith(expect.objectContaining({
+      sessionID: 'ses_1',
+      directory: '/repo',
+    }));
+  });
+
+  it('resumes an existing goal to active with statusReason resumed', async () => {
+    const existing = {
+      id: 'goal-1',
+      status: 'paused',
+      objective: 'keep going',
+      objectiveFile: false,
+      tokenBudget: null,
+      tokensUsed: 10,
+      turnsUsed: 1,
+      blockedStreak: 0,
+      note: '',
+      statusReason: '',
+      lastAccountedMessageID: 'msg_1',
+      createdAt: 1,
+      updatedAt: 2,
+    };
+    const readSessionMetadata = vi.fn(async () => ({
+      openchamber: { goal: existing },
+    }));
+    const persistSessionGoal = vi.fn(async (_id, _dir, goal) => ({
+      openchamber: { goal },
+    }));
+    const getRoute = register({ persistSessionGoal, readSessionMetadata });
+    const response = createResponse();
+    await getRoute('POST', '/api/goals/:sessionId/resume')({
+      params: { sessionId: 'ses_1' },
+      body: { directory: '/repo' },
+    }, response);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body.goal).toMatchObject({
+      id: 'goal-1',
+      status: 'active',
+      statusReason: 'resumed',
+      objective: 'keep going',
+    });
+    expect(persistSessionGoal).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns 404 on resume when no goal exists', async () => {
+    const readSessionMetadata = vi.fn(async () => ({}));
+    const persistSessionGoal = vi.fn();
+    const getRoute = register({ persistSessionGoal, readSessionMetadata });
+    const response = createResponse();
+    await getRoute('POST', '/api/goals/:sessionId/resume')({
+      params: { sessionId: 'ses_1' },
+    }, response);
+
+    expect(response.statusCode).toBe(404);
+    expect(persistSessionGoal).not.toHaveBeenCalled();
+  });
+
+  it('still allows objective read and delete for leftover files', async () => {
+    readObjective.mockClear();
+    deleteObjective.mockClear();
+    const getRoute = register();
+
+    const getResponse = createResponse();
+    await getRoute('GET', '/api/goals/objective/:sessionId')({
+      params: { sessionId: 'ses_1' },
+    }, getResponse);
+    expect(getResponse.statusCode).toBe(200);
+    expect(getResponse.body).toEqual({ content: 'leftover' });
+    expect(readObjective).toHaveBeenCalledWith('ses_1');
+
+    const deleteResponse = createResponse();
+    await getRoute('DELETE', '/api/goals/objective/:sessionId')({
+      params: { sessionId: 'ses_1' },
+    }, deleteResponse);
+    expect(deleteResponse.statusCode).toBe(200);
+    expect(deleteResponse.body.ok).toBe(true);
+    expect(deleteObjective).toHaveBeenCalledWith('ses_1');
+  });
+});