You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/08/23 16:14:15 UTC
(maka) branch main updated: refactor(desktop): extract goals as a feature slice (#3531)
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git
The following commit(s) were added to refs/heads/main by this push:
new 42cc5108c refactor(desktop): extract goals as a feature slice (#3531)
42cc5108c is described below
commit 42cc5108c21e8ae44afae765f3367467e0b6e031
Author: yum <ya...@chihum.dev>
AuthorDate: Mon Aug 24 00:14:11 2026 +0800
refactor(desktop): extract goals as a feature slice (#3531)
* refactor(desktop): extract goals as a feature slice
Move Goal state, subscriptions, controls, dialog ownership, and view-model assembly behind a renderer feature boundary and Desktop adapter. Add fake services, lifecycle tests, and architecture guardrails without changing the preload contract or user behavior.
Refs #3439
Generated-by: Codex
* chore: refresh Astryx surface inventory
Regenerate the checked-in surface inventory after moving the Goal dialog and adding the Goals feature service and host surfaces.
Refs #3439
Generated-by: Codex
---
.../src/main/__tests__/goal-arm-outcome.test.ts | 2 +-
.../src/main/__tests__/goal-controller.test.ts | 277 +++++++++++++++++++++
.../desktop/src/main/__tests__/goal-dialog.test.ts | 6 +-
apps/desktop/src/main/__tests__/goal-model.test.ts | 65 +++++
.../main/__tests__/goal-services-adapter.test.ts | 95 +++++++
.../src/main/__tests__/goals-boundary.test.ts | 103 ++++++++
apps/desktop/src/renderer/README.md | 4 +
apps/desktop/src/renderer/app-shell.tsx | 116 +--------
apps/desktop/src/renderer/features/goals/README.md | 64 +++++
.../goals/controller/use-goal-controller.ts | 241 ++++++++++++++++++
apps/desktop/src/renderer/features/goals/index.ts | 28 +++
.../{ => features/goals/model}/goal-arm-outcome.ts | 2 +-
.../renderer/features/goals/model/goal-budget.ts | 38 +++
.../src/renderer/features/goals/model/live-goal.ts | 40 +++
apps/desktop/src/renderer/features/goals/ports.ts | 46 ++++
.../renderer/features/goals/services-context.tsx | 40 +++
.../desktop/src/renderer/features/goals/testing.ts | 56 +++++
.../{ => features/goals/ui}/goal-dialog.tsx | 106 ++++----
.../src/renderer/features/goals/ui/goal-host.tsx | 39 +++
apps/desktop/src/renderer/main.tsx | 11 +-
.../platform/desktop/create-goal-services.ts | 42 ++++
apps/desktop/src/renderer/use-session-goal.ts | 92 -------
apps/desktop/stories/app-shell.stories.tsx | 25 +-
docs/astryx-surface-file-inventory.md | 4 +-
docs/astryx-surface-file-inventory.paths | 4 +-
25 files changed, 1288 insertions(+), 258 deletions(-)
diff --git a/apps/desktop/src/main/__tests__/goal-arm-outcome.test.ts b/apps/desktop/src/main/__tests__/goal-arm-outcome.test.ts
index 9f6e955e6..09a2b13c1 100644
--- a/apps/desktop/src/main/__tests__/goal-arm-outcome.test.ts
+++ b/apps/desktop/src/main/__tests__/goal-arm-outcome.test.ts
@@ -20,7 +20,7 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import type { GoalArmOutcome } from '../../shared/goal-arm.js';
-import { interpretGoalArmOutcome } from '../../renderer/goal-arm-outcome.js';
+import { interpretGoalArmOutcome } from '../../renderer/features/goals/testing.js';
import { getShellCopy } from '../../renderer/locales/shell-copy.js';
test('successful Goal arming closes while every reconciliation result locks the form', () => {
diff --git a/apps/desktop/src/main/__tests__/goal-controller.test.ts b/apps/desktop/src/main/__tests__/goal-controller.test.ts
new file mode 100644
index 000000000..d063a15fe
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/goal-controller.test.ts
@@ -0,0 +1,277 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { afterEach, describe, it } from 'node:test';
+import { act, createElement } from 'react';
+import type { GoalState, GoalStatus } from '@maka/core/goal';
+import { LocaleProvider } from '@maka/ui';
+import { cleanupFakeDom, installReactRenderer } from './fake-dom.js';
+import {
+ createFakeGoalServices,
+ GoalServicesProvider,
+ useGoalController,
+ type GoalController,
+ type GoalServices,
+ type UseGoalControllerInput,
+} from '../../renderer/features/goals/testing.js';
+
+function goal(
+ sessionId: string,
+ status: GoalStatus = 'active',
+): GoalState {
+ return {
+ id: `goal-${sessionId}`,
+ revision: 1,
+ sessionId,
+ condition: `Finish ${sessionId}`,
+ status,
+ setAt: 100,
+ iterations: 2,
+ maxIterations: 9,
+ consecutiveNoProgress: 0,
+ blockCap: 3,
+ tokenBudget: 500,
+ tokensAtStart: 10,
+ tokensNow: 60,
+ tokensBaselinePending: false,
+ ...(status === 'paused' ? { pausedAt: 200 } : {}),
+ };
+}
+
+function deferred<T>() {
+ let resolve!: (value: T) => void;
+ let reject!: (error: unknown) => void;
+ const promise = new Promise<T>((next, fail) => {
+ resolve = next;
+ reject = fail;
+ });
+ return { promise, resolve, reject };
+}
+
+let latestController: GoalController | undefined;
+
+function ControllerProbe(props: UseGoalControllerInput) {
+ latestController = useGoalController(props);
+ return null;
+}
+
+function renderController(
+ root: ReturnType<typeof installReactRenderer>['root'],
+ services: GoalServices,
+ input: UseGoalControllerInput,
+) {
+ root.render(
+ createElement(LocaleProvider, {
+ locale: 'en',
+ children: createElement(
+ GoalServicesProvider,
+ { services },
+ createElement(ControllerProbe, input),
+ ),
+ }),
+ );
+}
+
+function controller(): GoalController {
+ assert.ok(latestController);
+ return latestController;
+}
+
+function input(
+ activeSessionId: string | undefined,
+ errors: string[] = [],
+): UseGoalControllerInput {
+ return {
+ activeSessionId,
+ reportError: (sessionId, title, description) => {
+ errors.push(`${sessionId}: ${title}: ${description ?? ''}`);
+ },
+ };
+}
+
+afterEach(() => {
+ latestController = undefined;
+ cleanupFakeDom();
+});
+
+describe('useGoalController', () => {
+ it('clears on Session switch and ignores the previous Session late read', async () => {
+ const { root } = installReactRenderer();
+ const first = deferred<GoalState | null>();
+ let disposers = 0;
+ const defaults = createFakeGoalServices();
+ const services = createFakeGoalServices({
+ goal: {
+ ...defaults.goal,
+ get: (sessionId) =>
+ sessionId === 'a' ? first.promise : Promise.resolve(goal('b')),
+ subscribeChanges: () => () => {
+ disposers += 1;
+ },
+ },
+ });
+
+ await act(async () => renderController(root, services, input('a')));
+ assert.equal(controller().selectors.indicator, undefined);
+ await act(async () => renderController(root, services, input('b')));
+ assert.equal(controller().selectors.indicator?.condition, 'Finish b');
+ assert.equal(disposers, 1);
+
+ await act(async () => first.resolve(goal('a')));
+ assert.equal(controller().selectors.indicator?.condition, 'Finish b');
+
+ await act(async () => root.unmount());
+ assert.equal(disposers, 2);
+ });
+
+ it('refreshes for matching and broadcast Goal changes only', async () => {
+ const { root } = installReactRenderer();
+ let gets = 0;
+ let emit: ((sessionId: string | undefined) => void) | undefined;
+ const defaults = createFakeGoalServices();
+ const services = createFakeGoalServices({
+ goal: {
+ ...defaults.goal,
+ get: async () => {
+ gets += 1;
+ return gets === 2 ? goal('a', 'achieved') : goal('a');
+ },
+ subscribeChanges: (handler) => {
+ emit = handler;
+ return () => undefined;
+ },
+ },
+ });
+
+ await act(async () => renderController(root, services, input('a')));
+ assert.equal(gets, 1);
+ assert.equal(controller().selectors.active, true);
+
+ await act(async () => emit?.('other'));
+ assert.equal(gets, 1);
+
+ await act(async () => emit?.('a'));
+ assert.equal(gets, 2);
+ assert.equal(controller().selectors.active, false);
+
+ await act(async () => emit?.(undefined));
+ assert.equal(gets, 3);
+ assert.equal(controller().selectors.active, true);
+ });
+
+ it('snapshots the dialog Session across navigation and routes arm through the port', async () => {
+ const { root } = installReactRenderer();
+ const arms: unknown[][] = [];
+ const defaults = createFakeGoalServices();
+ const services = createFakeGoalServices({
+ goal: {
+ ...defaults.goal,
+ arm: async (...args) => {
+ arms.push(args);
+ return { kind: 'armed', goal: goal(args[0]) };
+ },
+ },
+ });
+
+ await act(async () => renderController(root, services, input('a')));
+ await act(async () => controller().commands.openDialog());
+ await act(async () => renderController(root, services, input('b')));
+
+ assert.equal(controller().host.dialogSessionId, 'a');
+ await act(async () =>
+ controller().host.arm(controller().host.dialogSessionId!, {
+ condition: 'ship it',
+ maxIterations: null,
+ tokenBudget: 1_000,
+ }),
+ );
+ assert.deepEqual(arms, [
+ ['a', { condition: 'ship it', maxIterations: null, tokenBudget: 1_000 }],
+ ]);
+ });
+
+ it('projects the kill switch and deduplicates pending pause controls', async () => {
+ const { root } = installReactRenderer();
+ const pause = deferred<void>();
+ let pauseCalls = 0;
+ const errors: string[] = [];
+ const defaults = createFakeGoalServices();
+ const services = createFakeGoalServices({
+ goal: {
+ ...defaults.goal,
+ get: async () => goal('a'),
+ pause: () => {
+ pauseCalls += 1;
+ return pauseCalls === 1 ? pause.promise : Promise.resolve();
+ },
+ },
+ });
+
+ await act(async () => renderController(root, services, input('a', errors)));
+ const indicator = controller().selectors.indicator;
+ assert.equal(indicator?.condition, 'Finish a');
+ assert.equal(indicator?.tokensSpent, 60);
+ assert.equal(indicator?.tokenBudget, 500);
+
+ await act(async () => {
+ indicator?.onPause?.();
+ indicator?.onPause?.();
+ });
+ assert.equal(pauseCalls, 1);
+
+ await act(async () => pause.reject(new Error('offline')));
+ assert.equal(errors.length, 1);
+ assert.equal(
+ errors[0],
+ 'a: Could not pause the goal: The goal may still be continuing. Try again now.',
+ );
+
+ await act(async () => controller().selectors.indicator?.onPause?.());
+ assert.equal(pauseCalls, 2);
+ });
+
+ it('routes resume and clear controls for paused Goals', async () => {
+ const { root } = installReactRenderer();
+ const calls: string[] = [];
+ const defaults = createFakeGoalServices();
+ const services = createFakeGoalServices({
+ goal: {
+ ...defaults.goal,
+ get: async () => goal('a', 'paused'),
+ clear: async (sessionId) => {
+ calls.push(`clear:${sessionId}`);
+ },
+ resume: async (sessionId) => {
+ calls.push(`resume:${sessionId}`);
+ },
+ },
+ });
+
+ await act(async () => renderController(root, services, input('a')));
+ const indicator = controller().selectors.indicator;
+ assert.equal(indicator?.status, 'paused');
+ assert.equal(indicator?.pausedAt, 200);
+ await act(async () => {
+ indicator?.onResume?.();
+ indicator?.onClear();
+ });
+ assert.deepEqual(calls, ['resume:a', 'clear:a']);
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/goal-dialog.test.ts b/apps/desktop/src/main/__tests__/goal-dialog.test.ts
index 353ba9d3f..30c18dc37 100644
--- a/apps/desktop/src/main/__tests__/goal-dialog.test.ts
+++ b/apps/desktop/src/main/__tests__/goal-dialog.test.ts
@@ -24,7 +24,7 @@ import { createRoot, type Root } from 'react-dom/client';
import { parseHTML } from 'linkedom';
import { AstryxLocaleProvider, LocaleProvider } from '@maka/ui';
import type { GoalArmOutcome } from '../../shared/goal-arm.js';
-import { GoalDialog } from '../../renderer/goal-dialog.js';
+import { GoalDialog } from '../../renderer/features/goals/testing.js';
const originalGlobals = {
document: globalThis.document,
@@ -171,9 +171,6 @@ function installGoalDialog(
cancelAnimationFrame: (handle: number) => clearTimeout(handle),
IS_REACT_ACT_ENVIRONMENT: true,
});
- (window as unknown as { maka: unknown }).maka = {
- goal: { arm },
- };
const container = document.querySelector('#root');
assert.ok(container);
const root = createRoot(container);
@@ -192,6 +189,7 @@ function installGoalDialog(
children: createElement(AstryxLocaleProvider, {
children: createElement(GoalDialog, {
sessionId,
+ onArm: arm,
onClose: () => {
closed += 1;
},
diff --git a/apps/desktop/src/main/__tests__/goal-model.test.ts b/apps/desktop/src/main/__tests__/goal-model.test.ts
new file mode 100644
index 000000000..986f7d746
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/goal-model.test.ts
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import type { GoalState, GoalStatus } from '@maka/core/goal';
+import {
+ isLiveGoal,
+ readGoalBudget,
+} from '../../renderer/features/goals/testing.js';
+
+function goal(status: GoalStatus, pausedAt?: number): GoalState {
+ return {
+ id: 'goal-1',
+ revision: 1,
+ sessionId: 'session-1',
+ condition: 'Finish the refactor',
+ status,
+ setAt: 1,
+ iterations: 2,
+ maxIterations: 10,
+ consecutiveNoProgress: 0,
+ blockCap: 3,
+ tokensAtStart: 0,
+ tokensNow: 50,
+ tokensBaselinePending: false,
+ ...(pausedAt === undefined ? {} : { pausedAt }),
+ };
+}
+
+describe('Goals model', () => {
+ it('parses only whole, bounded, safe budget values', () => {
+ assert.deepEqual(readGoalBudget(' ', 1, 10), { kind: 'empty' });
+ assert.deepEqual(readGoalBudget('7', 1, 10), { kind: 'value', value: 7 });
+ for (const invalid of ['0', '11', '-1', '1.5', '1e2', '9007199254740992']) {
+ assert.deepEqual(readGoalBudget(invalid, 1, 10), { kind: 'invalid' });
+ }
+ });
+
+ it('projects only running and well-formed paused Goals', () => {
+ assert.equal(isLiveGoal(goal('active')), true);
+ assert.equal(isLiveGoal(goal('waiting')), true);
+ assert.equal(isLiveGoal(goal('paused', 12)), true);
+ assert.equal(isLiveGoal(goal('paused')), false);
+ assert.equal(isLiveGoal(goal('paused', Number.NaN)), false);
+ assert.equal(isLiveGoal(goal('achieved')), false);
+ assert.equal(isLiveGoal(goal('cleared')), false);
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/goal-services-adapter.test.ts b/apps/desktop/src/main/__tests__/goal-services-adapter.test.ts
new file mode 100644
index 000000000..e82445224
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/goal-services-adapter.test.ts
@@ -0,0 +1,95 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import type { SessionChangedEvent } from '@maka/core/session';
+import type { MakaBridge } from '../../preload/bridge-contract.js';
+import { createDesktopGoalServices } from '../../renderer/platform/desktop/create-goal-services.js';
+
+describe('createDesktopGoalServices', () => {
+ it('maps Goal operations and narrows Session changes to Goal events', async () => {
+ const calls: Array<{ name: string; args: unknown[] }> = [];
+ let sessionHandler: ((event: SessionChangedEvent) => void) | undefined;
+ let disposed = 0;
+ const bridge = {
+ goal: new Proxy({}, {
+ get: (_target, property) => (...args: unknown[]) => {
+ calls.push({ name: `goal.${String(property)}`, args });
+ return Promise.resolve(undefined);
+ },
+ }),
+ sessions: {
+ subscribeChanges(handler: (event: SessionChangedEvent) => void) {
+ sessionHandler = handler;
+ return () => {
+ disposed += 1;
+ };
+ },
+ },
+ } as unknown as MakaBridge;
+ const services = createDesktopGoalServices(bridge);
+
+ await services.goal.get('s');
+ await services.goal.arm('s', {
+ condition: 'done',
+ maxIterations: 4,
+ tokenBudget: null,
+ });
+ await services.goal.clear('s');
+ await services.goal.pause('s');
+ await services.goal.resume('s');
+
+ const changes: Array<string | undefined> = [];
+ const unsubscribe = services.goal.subscribeChanges((sessionId) => {
+ changes.push(sessionId);
+ });
+ sessionHandler?.({
+ type: 'sessions_changed',
+ reason: 'updated',
+ sessionId: 'ignored',
+ ts: 1,
+ });
+ sessionHandler?.({
+ type: 'sessions_changed',
+ reason: 'goal-change',
+ sessionId: 's',
+ ts: 2,
+ });
+ sessionHandler?.({
+ type: 'sessions_changed',
+ reason: 'goal-change',
+ ts: 3,
+ });
+ unsubscribe();
+
+ assert.deepEqual(calls, [
+ { name: 'goal.get', args: ['s'] },
+ {
+ name: 'goal.arm',
+ args: ['s', { condition: 'done', maxIterations: 4, tokenBudget: null }],
+ },
+ { name: 'goal.clear', args: ['s'] },
+ { name: 'goal.pause', args: ['s'] },
+ { name: 'goal.resume', args: ['s'] },
+ ]);
+ assert.deepEqual(changes, ['s', undefined]);
+ assert.equal(disposed, 1);
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/goals-boundary.test.ts b/apps/desktop/src/main/__tests__/goals-boundary.test.ts
new file mode 100644
index 000000000..7078ea94c
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/goals-boundary.test.ts
@@ -0,0 +1,103 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { strict as assert } from 'node:assert';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const desktopRoot = resolve(fileURLToPath(new URL('../../../', import.meta.url)));
+const featureRoot = join(desktopRoot, 'src', 'renderer', 'features', 'goals');
+
+function sourceFiles(root: string): string[] {
+ return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+ const path = join(root, entry.name);
+ if (entry.isDirectory()) return sourceFiles(path);
+ return /\.(?:ts|tsx|md)$/.test(entry.name) ? [path] : [];
+ });
+}
+
+describe('Goals feature boundary', () => {
+ it('contains no Desktop global bridge or shell/process imports', () => {
+ const violations: string[] = [];
+ for (const path of sourceFiles(featureRoot)) {
+ const source = readFileSync(path, 'utf8');
+ const name = relative(desktopRoot, path);
+ if (source.includes('window.maka')) violations.push(`${name}: Desktop global`);
+ for (const match of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+ const imported = match[1] ?? '';
+ if (
+ imported.includes('app-shell') ||
+ imported.includes('/preload/') ||
+ imported.includes('/main/')
+ ) {
+ violations.push(`${name}: ${imported}`);
+ }
+ }
+ }
+ assert.deepEqual(violations, []);
+ });
+
+ it('is consumed outside the feature only through public entries', () => {
+ const allowed = /\/features\/goals\/(?:index|testing)(?:\.js)?$/;
+ const violations: string[] = [];
+ for (const root of [join(desktopRoot, 'src'), join(desktopRoot, 'stories')]) {
+ for (const path of sourceFiles(root)) {
+ if (path.startsWith(featureRoot)) continue;
+ const source = readFileSync(path, 'utf8');
+ for (const match of source.matchAll(/from\s+['"]([^'"]*features\/goals[^'"]*)['"]/g)) {
+ const imported = match[1] ?? '';
+ const normalized = imported.replace(/\\/g, '/');
+ const explicitEntry = normalized.endsWith('/features/goals')
+ ? `${normalized}/index`
+ : normalized;
+ if (!allowed.test(explicitEntry)) {
+ violations.push(`${relative(desktopRoot, path)}: ${imported}`);
+ }
+ }
+ }
+ }
+ assert.deepEqual(violations, []);
+ });
+
+ it('keeps fake services out of the production entry', () => {
+ const productionEntry = readFileSync(join(featureRoot, 'index.ts'), 'utf8');
+ assert.equal(productionEntry.includes('createFakeGoalServices'), false);
+ assert.equal(productionEntry.includes("from './testing"), false);
+ });
+
+ it('keeps Goal state, controls, and dialog ownership out of AppShell', () => {
+ const appShell = readFileSync(
+ join(desktopRoot, 'src', 'renderer', 'app-shell.tsx'),
+ 'utf8',
+ );
+ for (const forbidden of [
+ 'window.maka.goal',
+ 'useSessionGoal',
+ 'pendingGoalControlSessionIdsRef',
+ 'goalDialogSessionId',
+ 'setGoalDialogSessionId',
+ ]) {
+ assert.equal(appShell.includes(forbidden), false, forbidden);
+ }
+ assert.equal(appShell.includes('const goals = useGoalController({'), true);
+ assert.equal(appShell.includes('<GoalHost model={goals.host} />'), true);
+ });
+});
diff --git a/apps/desktop/src/renderer/README.md b/apps/desktop/src/renderer/README.md
index 183799bf3..f95082b7d 100644
--- a/apps/desktop/src/renderer/README.md
+++ b/apps/desktop/src/renderer/README.md
@@ -41,6 +41,10 @@ shell logic split by one concern (e.g. `app-shell-session-events.ts`,
`app-shell-overlays.tsx`). Keep a slice to one concern; if it grows, split along
the same seam.
+Autonomous Goal state, controls, dialog lifecycle, and Desktop I/O live under
+`features/goals`; AppShell supplies the active Session boundary and consumes
+the feature's host, commands, and selectors.
+
`settings/` holds the settings pages and the `SettingsModal` shell — one page per `SettingsSection` (defined in `@maka/core`); the models/providers page is `ProvidersPanel`. Plus the `provider-*` files and the shared `settings-rows` / `settings-skeleton` / `settings-surface` helpers.
## Styles & tokens
diff --git a/apps/desktop/src/renderer/app-shell.tsx b/apps/desktop/src/renderer/app-shell.tsx
index e4c672483..e1059c625 100644
--- a/apps/desktop/src/renderer/app-shell.tsx
+++ b/apps/desktop/src/renderer/app-shell.tsx
@@ -99,6 +99,7 @@ import {
WorkbarTitlebarActions,
useWorkbarController,
} from './features/workbar';
+import { GoalHost, useGoalController } from './features/goals';
import { UNRESOLVED_NEW_TASK_DRAFT_KEY } from './new-task-reload-intent';
import { useNewTaskChoice } from './use-new-task-choice';
import { NEW_TASK_PENDING_KEY } from './pending-items';
@@ -137,7 +138,6 @@ import { getDesktopConversationCopy } from './locales/conversation-copy';
import { ErrorBoundary } from './error-boundary';
import { useShellAppearance } from './use-shell-appearance';
import { useShellSearch } from './use-shell-search';
-import { useSessionGoal } from './use-session-goal';
import { deriveStaleSessionIds } from './stale-sessions';
import { pendingSessionView } from './pending-session-view';
import { deriveProjectGroups, deriveWorktreeSessionIds } from './session-project-grouping';
@@ -251,7 +251,6 @@ function rebaseWorkspaceFileReferences(
import { useSettingsModal } from './use-settings-modal';
import { RemoteProjectDirectoryDialog } from './remote-project-directory-dialog';
-import { GoalDialog } from './goal-dialog.js';
import { useSystemUiLocale } from './use-system-ui-locale';
import {
isSessionWorkspaceUnavailableError,
@@ -776,31 +775,10 @@ function AppShellContent({
resumeInterruptedSession,
} = useShellResume({ activeId, toastApi, shellCopy, uiLocale });
const rendererMountedRef = useRef(true);
- // Active autonomous goal for the current session drives the header
- // kill-switch pill (visible indicator + one-click clear).
- const activeGoal = useSessionGoal(activeId);
- const pendingGoalControlSessionIdsRef = useRef(new Set<string>());
- const runGoalControl = useCallback(
- (
- sessionId: string,
- operation: () => Promise<unknown>,
- reportFailure: (error: unknown) => void,
- ): void => {
- const pending = pendingGoalControlSessionIdsRef.current;
- if (pending.has(sessionId)) return;
- pending.add(sessionId);
- void operation()
- .catch(reportFailure)
- .finally(() => pending.delete(sessionId));
- },
- [],
- );
- /**
- * The Session the Goal dialog is arming, or `undefined` when it is closed.
- * Keyed by Session rather than a boolean so switching Sessions while the
- * dialog is open can never arm the wrong one.
- */
- const [goalDialogSessionId, setGoalDialogSessionId] = useState<string>();
+ const goals = useGoalController({
+ activeSessionId: activeId,
+ reportError: showSessionError,
+ });
// Set of session ids whose backend / connection is no longer usable —
// drives the sidebar "已过期" pill (PR108g, paired with the PR108e chat
// header banner). Derivation is pure (see `stale-sessions.ts`) so the
@@ -3242,10 +3220,10 @@ function AppShellContent({
}}
onSetGoal={
activeId && activeBoundarySurface.localInteractionAvailable
- ? () => setGoalDialogSessionId(activeId)
+ ? goals.commands.openDialog
: undefined
}
- goalActive={activeGoal !== null}
+ goalActive={goals.selectors.active}
goalDisabledReason={
activeStreamingLive || (activeId && turnActive)
? shellCopy.goalTurnActive
@@ -3282,80 +3260,7 @@ function AppShellContent({
userLabel={userLabel}
memoryActive={memoryActive}
onOpenMemorySettings={() => openSettingsSection('memory')}
- goalIndicator={
- activeGoal
- ? (() => {
- const common = {
- condition: activeGoal.condition,
- iterations: activeGoal.iterations,
- maxIterations: activeGoal.maxIterations,
- setAt: activeGoal.setAt,
- tokensSpent: activeGoal.tokensNow,
- ...(activeGoal.tokenBudget !== undefined
- ? { tokenBudget: activeGoal.tokenBudget }
- : {}),
- onClear: () => {
- void window.maka.goal.clear(activeGoal.sessionId).catch((error) => {
- showSessionError(
- activeGoal.sessionId,
- shellCopy.goalClearFailedTitle,
- localizedShellErrorMessage(
- error,
- shellCopy.goalClearFailedFallback,
- uiLocale,
- ),
- );
- });
- },
- };
- if (activeGoal.status === 'paused') {
- return {
- ...common,
- status: 'paused' as const,
- pausedAt: activeGoal.pausedAt,
- onResume: () => {
- runGoalControl(
- activeGoal.sessionId,
- () => window.maka.goal.resume(activeGoal.sessionId),
- (error) => {
- showSessionError(
- activeGoal.sessionId,
- shellCopy.goalResumeFailedTitle,
- localizedShellErrorMessage(
- error,
- shellCopy.goalResumeFailedFallback,
- uiLocale,
- ),
- );
- },
- );
- },
- };
- }
- return {
- ...common,
- status: activeGoal.status,
- onPause: () => {
- runGoalControl(
- activeGoal.sessionId,
- () => window.maka.goal.pause(activeGoal.sessionId),
- (error) => {
- showSessionError(
- activeGoal.sessionId,
- shellCopy.goalPauseFailedTitle,
- localizedShellErrorMessage(
- error,
- shellCopy.goalPauseFailedFallback,
- uiLocale,
- ),
- );
- },
- );
- },
- };
- })()
- : undefined
- }
+ goalIndicator={goals.selectors.indicator}
messageLoadError={activeId ? messageLoadErrorBySession[activeId] : undefined}
messageLoadRetryPending={activeId ? messageRetryPendingBySession[activeId] === true : false}
onRetryMessages={activeId ? () => void retryMessages(activeId) : undefined}
@@ -3486,10 +3391,7 @@ function AppShellContent({
contextKey={activeId}
/>
)}
- <GoalDialog
- {...(goalDialogSessionId ? { sessionId: goalDialogSessionId } : {})}
- onClose={() => setGoalDialogSessionId(undefined)}
- />
+ <GoalHost model={goals.host} />
<RuntimeHostSshTerminalDialog />
<RemoteProjectDirectoryDialog
diff --git a/apps/desktop/src/renderer/features/goals/README.md b/apps/desktop/src/renderer/features/goals/README.md
new file mode 100644
index 000000000..6f56fd73e
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/README.md
@@ -0,0 +1,64 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Goals feature
+
+Goals is a vertical renderer feature. It owns the active Goal read model,
+Goal-change subscription, arm/pause/resume/clear controls, dialog target, and
+the Goal indicator projection consumed by the chat surface.
+
+## Dependency direction
+
+- Consumers import production APIs from `features/goals`.
+- Tests and stories may additionally import `features/goals/testing`.
+- Goals may use shared renderer copy, core types, and Maka UI.
+- Goals must not import `AppShell`, the preload implementation, or the main process.
+- Desktop I/O enters through `GoalServices`; feature code never reads the
+ Desktop global bridge directly.
+- `AppShell` supplies the active Session id and a session-scoped error reporter.
+ It consumes only `<GoalHost>`, commands, and selectors.
+
+## Lifecycle invariants
+
+- A Goal is session-scoped. Switching Sessions clears the previous read model
+ synchronously and fences late reads before fetching the new Goal.
+- Only `active`, `waiting`, and well-formed `paused` Goals are projected. A
+ settled Goal removes the indicator and composer active state.
+- Goal-change broadcasts refresh the active Session; events for another
+ Session do not.
+- Pause and resume are mutually exclusive per Session while a control request
+ is pending, preserving the existing re-entry guard.
+- Opening the dialog snapshots the active Session id. Navigating while it is
+ open cannot retarget the arm request to a different Session.
+- A reconnecting arm result closes only when the Host confirms a new Goal.
+ Reconciled or unavailable results lock the form and show the authoritative
+ outcome, preventing an accidental duplicate arm request.
+- Form input and errors reset on each open. Budgets are validated against core
+ bounds and are never silently clamped.
+
+## Public surface
+
+- `host` is passed intact to `<GoalHost model={goals.host} />`.
+- `commands.openDialog` is the shell entry for the composer action.
+- `selectors.active` disables duplicate Goal creation and
+ `selectors.indicator` feeds the active chat surface.
+
+The Desktop adapter is created once in the renderer composition root. Tests
+use `createFakeGoalServices` from `testing.ts`; production code must not import
+that entry.
diff --git a/apps/desktop/src/renderer/features/goals/controller/use-goal-controller.ts b/apps/desktop/src/renderer/features/goals/controller/use-goal-controller.ts
new file mode 100644
index 000000000..09ad21e35
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/controller/use-goal-controller.ts
@@ -0,0 +1,241 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type ComponentProps,
+} from 'react';
+import { useUiLocale, type ChatView } from '@maka/ui';
+import {
+ getShellCopy,
+ localizedShellErrorMessage,
+} from '../../../locales/shell-copy.js';
+import { isLiveGoal, type LiveGoalState } from '../model/live-goal.js';
+import type { GoalArmInput, GoalArmOutcome } from '../ports.js';
+import { useGoalServices } from '../services-context.js';
+import type { GoalHostModel } from '../ui/goal-host.js';
+
+type GoalIndicator = NonNullable<
+ ComponentProps<typeof ChatView>['goalIndicator']
+>;
+
+export interface GoalControllerCommands {
+ /** Opens for the current Session and snapshots that id until close. */
+ openDialog(): void;
+}
+
+export interface GoalControllerSelectors {
+ active: boolean;
+ indicator?: GoalIndicator;
+}
+
+export interface UseGoalControllerInput {
+ activeSessionId: string | undefined;
+ reportError(sessionId: string, title: string, description?: string): void;
+}
+
+export interface GoalController {
+ host: GoalHostModel;
+ commands: GoalControllerCommands;
+ selectors: GoalControllerSelectors;
+}
+
+/** Owns all renderer Goal state, controls, subscriptions, and dialog lifecycle. */
+export function useGoalController(
+ input: UseGoalControllerInput,
+): GoalController {
+ const locale = useUiLocale();
+ const copy = getShellCopy(locale).app;
+ const { goal: service } = useGoalServices();
+ const [activeGoal, setActiveGoal] = useState<LiveGoalState | null>(null);
+ const [dialogSessionId, setDialogSessionId] = useState<string>();
+ const pendingControlSessionIdsRef = useRef(new Set<string>());
+
+ useEffect(() => {
+ const sessionId = input.activeSessionId;
+ if (!sessionId) {
+ setActiveGoal(null);
+ return;
+ }
+
+ setActiveGoal(null);
+ let disposed = false;
+ let refreshSequence = 0;
+ const refresh = (): void => {
+ const sequence = ++refreshSequence;
+ void service
+ .get(sessionId)
+ .then((goal) => {
+ if (disposed || sequence !== refreshSequence) return;
+ setActiveGoal(goal && isLiveGoal(goal) ? goal : null);
+ })
+ .catch(() => {
+ if (!disposed && sequence === refreshSequence) setActiveGoal(null);
+ });
+ };
+
+ refresh();
+ const unsubscribe = service.subscribeChanges((changedSessionId) => {
+ if (!changedSessionId || changedSessionId === sessionId) refresh();
+ });
+ return () => {
+ disposed = true;
+ refreshSequence += 1;
+ unsubscribe();
+ };
+ }, [input.activeSessionId, service]);
+
+ const reportControlFailure = useCallback(
+ (
+ sessionId: string,
+ error: unknown,
+ title: string,
+ fallback: string,
+ ): void => {
+ input.reportError(
+ sessionId,
+ title,
+ localizedShellErrorMessage(error, fallback, locale),
+ );
+ },
+ [input.reportError, locale],
+ );
+
+ const runExclusiveControl = useCallback(
+ (
+ sessionId: string,
+ operation: () => Promise<void>,
+ reportFailure: (error: unknown) => void,
+ ): void => {
+ const pending = pendingControlSessionIdsRef.current;
+ if (pending.has(sessionId)) return;
+ pending.add(sessionId);
+ void operation()
+ .catch(reportFailure)
+ .finally(() => pending.delete(sessionId));
+ },
+ [],
+ );
+
+ const indicator = useMemo<GoalIndicator | undefined>(() => {
+ if (!activeGoal) return undefined;
+ const common = {
+ condition: activeGoal.condition,
+ iterations: activeGoal.iterations,
+ maxIterations: activeGoal.maxIterations,
+ setAt: activeGoal.setAt,
+ tokensSpent: activeGoal.tokensNow,
+ ...(activeGoal.tokenBudget !== undefined
+ ? { tokenBudget: activeGoal.tokenBudget }
+ : {}),
+ onClear: () => {
+ void service.clear(activeGoal.sessionId).catch((error) => {
+ reportControlFailure(
+ activeGoal.sessionId,
+ error,
+ copy.goalClearFailedTitle,
+ copy.goalClearFailedFallback,
+ );
+ });
+ },
+ };
+
+ if (activeGoal.status === 'paused') {
+ return {
+ ...common,
+ status: 'paused',
+ pausedAt: activeGoal.pausedAt,
+ onResume: () => {
+ runExclusiveControl(
+ activeGoal.sessionId,
+ () => service.resume(activeGoal.sessionId),
+ (error) => {
+ reportControlFailure(
+ activeGoal.sessionId,
+ error,
+ copy.goalResumeFailedTitle,
+ copy.goalResumeFailedFallback,
+ );
+ },
+ );
+ },
+ };
+ }
+
+ return {
+ ...common,
+ status: activeGoal.status,
+ onPause: () => {
+ runExclusiveControl(
+ activeGoal.sessionId,
+ () => service.pause(activeGoal.sessionId),
+ (error) => {
+ reportControlFailure(
+ activeGoal.sessionId,
+ error,
+ copy.goalPauseFailedTitle,
+ copy.goalPauseFailedFallback,
+ );
+ },
+ );
+ },
+ };
+ }, [
+ activeGoal,
+ copy.goalClearFailedFallback,
+ copy.goalClearFailedTitle,
+ copy.goalPauseFailedFallback,
+ copy.goalPauseFailedTitle,
+ copy.goalResumeFailedFallback,
+ copy.goalResumeFailedTitle,
+ reportControlFailure,
+ runExclusiveControl,
+ service,
+ ]);
+
+ const openDialog = useCallback(() => {
+ if (input.activeSessionId) setDialogSessionId(input.activeSessionId);
+ }, [input.activeSessionId]);
+ const closeDialog = useCallback(() => setDialogSessionId(undefined), []);
+ const arm = useCallback(
+ (sessionId: string, request: GoalArmInput): Promise<GoalArmOutcome> =>
+ service.arm(sessionId, request),
+ [service],
+ );
+
+ return useMemo(
+ () => ({
+ host: {
+ ...(dialogSessionId ? { dialogSessionId } : {}),
+ arm,
+ closeDialog,
+ },
+ commands: { openDialog },
+ selectors: {
+ active: activeGoal !== null,
+ ...(indicator ? { indicator } : {}),
+ },
+ }),
+ [activeGoal, arm, closeDialog, dialogSessionId, indicator, openDialog],
+ );
+}
diff --git a/apps/desktop/src/renderer/features/goals/index.ts b/apps/desktop/src/renderer/features/goals/index.ts
new file mode 100644
index 000000000..ac3d7768d
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/index.ts
@@ -0,0 +1,28 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export { GoalHost } from './ui/goal-host';
+export { GoalServicesProvider } from './services-context';
+export {
+ useGoalController,
+ type GoalController,
+ type GoalControllerCommands,
+ type GoalControllerSelectors,
+} from './controller/use-goal-controller';
+export type { GoalArmInput, GoalServices } from './ports';
diff --git a/apps/desktop/src/renderer/goal-arm-outcome.ts b/apps/desktop/src/renderer/features/goals/model/goal-arm-outcome.ts
similarity index 96%
rename from apps/desktop/src/renderer/goal-arm-outcome.ts
rename to apps/desktop/src/renderer/features/goals/model/goal-arm-outcome.ts
index a3d065b78..9094eeda6 100644
--- a/apps/desktop/src/renderer/goal-arm-outcome.ts
+++ b/apps/desktop/src/renderer/features/goals/model/goal-arm-outcome.ts
@@ -18,7 +18,7 @@
*/
import type { GoalState } from '@maka/runtime/goal-state';
-import type { GoalArmOutcome } from '../shared/goal-arm.js';
+import type { GoalArmOutcome } from '../../../../shared/goal-arm.js';
export type GoalArmReconciliationNotice =
| { readonly kind: 'matching_goal'; readonly goal: GoalState }
diff --git a/apps/desktop/src/renderer/features/goals/model/goal-budget.ts b/apps/desktop/src/renderer/features/goals/model/goal-budget.ts
new file mode 100644
index 000000000..a235165c4
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/model/goal-budget.ts
@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export type GoalBudgetReading =
+ | { readonly kind: 'empty' }
+ | { readonly kind: 'value'; readonly value: number }
+ | { readonly kind: 'invalid' };
+
+/** Parses a form budget without silently clamping or retaining stale input. */
+export function readGoalBudget(
+ text: string,
+ min: number,
+ max?: number,
+): GoalBudgetReading {
+ const trimmed = text.trim();
+ if (!trimmed) return { kind: 'empty' };
+ if (!/^\d+$/.test(trimmed)) return { kind: 'invalid' };
+ const value = Number(trimmed);
+ if (!Number.isSafeInteger(value) || value < min) return { kind: 'invalid' };
+ if (max !== undefined && value > max) return { kind: 'invalid' };
+ return { kind: 'value', value };
+}
diff --git a/apps/desktop/src/renderer/features/goals/model/live-goal.ts b/apps/desktop/src/renderer/features/goals/model/live-goal.ts
new file mode 100644
index 000000000..2acac1350
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/model/live-goal.ts
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { GoalState, GoalStatus } from '@maka/core/goal';
+
+type LiveGoalStatus = Extract<GoalStatus, 'active' | 'waiting'>;
+
+export type LiveGoalState =
+ | (GoalState & { readonly status: LiveGoalStatus })
+ | (GoalState & { readonly status: 'paused'; readonly pausedAt: number });
+
+const LIVE_GOAL_STATUSES: ReadonlySet<GoalStatus> = new Set([
+ 'active',
+ 'waiting',
+ 'paused',
+]);
+
+export function isLiveGoal(goal: GoalState): goal is LiveGoalState {
+ return (
+ LIVE_GOAL_STATUSES.has(goal.status) &&
+ (goal.status !== 'paused' ||
+ (typeof goal.pausedAt === 'number' && Number.isFinite(goal.pausedAt)))
+ );
+}
diff --git a/apps/desktop/src/renderer/features/goals/ports.ts b/apps/desktop/src/renderer/features/goals/ports.ts
new file mode 100644
index 000000000..486ea6d3f
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/ports.ts
@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { GoalState } from '@maka/core/goal';
+import type { GoalArmOutcome } from '../../../shared/goal-arm.js';
+
+export type { GoalArmOutcome } from '../../../shared/goal-arm.js';
+
+export type GoalUnsubscribe = () => void;
+
+export interface GoalArmInput {
+ readonly condition: string;
+ readonly maxIterations?: number | null;
+ readonly tokenBudget?: number | null;
+}
+
+/** The minimum environment capability needed by the Goals feature. */
+export interface GoalService {
+ get(sessionId: string): Promise<GoalState | null>;
+ arm(sessionId: string, goal: GoalArmInput): Promise<GoalArmOutcome>;
+ clear(sessionId: string): Promise<void>;
+ pause(sessionId: string): Promise<void>;
+ resume(sessionId: string): Promise<void>;
+ /** Emits a Session id, or `undefined` for a broadcast Goal transition. */
+ subscribeChanges(handler: (sessionId: string | undefined) => void): GoalUnsubscribe;
+}
+
+export interface GoalServices {
+ goal: GoalService;
+}
diff --git a/apps/desktop/src/renderer/features/goals/services-context.tsx b/apps/desktop/src/renderer/features/goals/services-context.tsx
new file mode 100644
index 000000000..65efb5120
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/services-context.tsx
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+import type { GoalServices } from './ports.js';
+
+const GoalServicesContext = createContext<GoalServices | null>(null);
+
+export function GoalServicesProvider(props: {
+ services: GoalServices;
+ children?: ReactNode;
+}) {
+ return (
+ <GoalServicesContext.Provider value={props.services}>
+ {props.children}
+ </GoalServicesContext.Provider>
+ );
+}
+
+export function useGoalServices(): GoalServices {
+ const services = useContext(GoalServicesContext);
+ if (!services) throw new Error('GoalServicesProvider is missing');
+ return services;
+}
diff --git a/apps/desktop/src/renderer/features/goals/testing.ts b/apps/desktop/src/renderer/features/goals/testing.ts
new file mode 100644
index 000000000..83a81b987
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/testing.ts
@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { GoalServices } from './ports.js';
+
+export { GoalServicesProvider } from './services-context.js';
+export { GoalDialog } from './ui/goal-dialog.js';
+export { readGoalBudget } from './model/goal-budget.js';
+export { isLiveGoal, type LiveGoalState } from './model/live-goal.js';
+export {
+ interpretGoalArmOutcome,
+ type GoalArmOutcomeAction,
+ type GoalArmReconciliationNotice,
+} from './model/goal-arm-outcome.js';
+export {
+ useGoalController,
+ type GoalController,
+ type UseGoalControllerInput,
+} from './controller/use-goal-controller.js';
+export type { GoalArmInput, GoalArmOutcome, GoalServices } from './ports.js';
+
+const noopSubscription = (): (() => void) => () => undefined;
+
+export function createFakeGoalServices(
+ overrides: Partial<GoalServices> = {},
+): GoalServices {
+ return {
+ goal: {
+ get: async () => null,
+ arm: async () => {
+ throw new Error('Fake goal.arm is not configured');
+ },
+ clear: async () => undefined,
+ pause: async () => undefined,
+ resume: async () => undefined,
+ subscribeChanges: noopSubscription,
+ },
+ ...overrides,
+ };
+}
diff --git a/apps/desktop/src/renderer/goal-dialog.tsx b/apps/desktop/src/renderer/features/goals/ui/goal-dialog.tsx
similarity index 75%
rename from apps/desktop/src/renderer/goal-dialog.tsx
rename to apps/desktop/src/renderer/features/goals/ui/goal-dialog.tsx
index 7418547b5..36b5a5690 100644
--- a/apps/desktop/src/renderer/goal-dialog.tsx
+++ b/apps/desktop/src/renderer/features/goals/ui/goal-dialog.tsx
@@ -18,7 +18,7 @@
*/
/**
- * The form behind the + menu's "Set a goal…" entry.
+ * The form behind the composer menu's "Set a goal…" entry.
*
* A Goal is the one control here that keeps spending tokens after the user
* stops typing, so it is a dialog rather than a menu row: the condition needs
@@ -27,11 +27,7 @@
*
* Bounds are the Host's. This sends what the user chose and reports what the
* Host answers; it does not clamp a rejected number into an accepted one,
- * because the Goal that then runs would not be the one they asked for. For the
- * same reason the budget fields hold the user's own text rather than a parsed
- * number: a field that quietly keeps the last value it could parse can arm a
- * budget the form is no longer showing, and a field that quietly keeps nothing
- * can arm no budget at all where the user asked for a tight one.
+ * because the Goal that then runs would not be the one they asked for.
*/
import { useLayoutEffect, useRef, useState } from 'react';
import { Button } from '@astryxdesign/core/Button';
@@ -41,46 +37,31 @@ import { HStack, VStack } from '@astryxdesign/core/Stack';
import { Text } from '@astryxdesign/core/Text';
import { TextArea } from '@astryxdesign/core/TextArea';
import { TextInput } from '@astryxdesign/core/TextInput';
-import { useUiLocale } from '@maka/ui';
import {
GOAL_CONDITION_TEXT_LIMIT,
GOAL_MAX_ITERATIONS_LIMIT,
GOAL_TOKEN_BUDGET_MINIMUM,
} from '@maka/core/goal';
-import { getShellCopy, localizedShellErrorMessage } from './locales/shell-copy.js';
+import { useUiLocale } from '@maka/ui';
+import {
+ getShellCopy,
+ localizedShellErrorMessage,
+} from '../../../locales/shell-copy.js';
import {
interpretGoalArmOutcome,
type GoalArmReconciliationNotice,
-} from './goal-arm-outcome.js';
-
-type BudgetReading =
- | { readonly kind: 'empty' }
- | { readonly kind: 'value'; readonly value: number }
- | { readonly kind: 'invalid' };
-
-/**
- * Read one budget field, refusing anything the Host would not take.
- *
- * `min`/`max` repeat the operation's own bounds so the refusal can be shown
- * beside the field instead of arriving as a rejected frame; the numbers
- * themselves come from the shared Goal limits, so there is still one authority
- * for what they are.
- */
-function readGoalBudget(text: string, min: number, max?: number): BudgetReading {
- const trimmed = text.trim();
- if (!trimmed) return { kind: 'empty' };
- if (!/^\d+$/.test(trimmed)) return { kind: 'invalid' };
- const value = Number(trimmed);
- if (!Number.isSafeInteger(value) || value < min) return { kind: 'invalid' };
- if (max !== undefined && value > max) return { kind: 'invalid' };
- return { kind: 'value', value };
-}
+} from '../model/goal-arm-outcome.js';
+import { readGoalBudget } from '../model/goal-budget.js';
+import type { GoalArmInput, GoalArmOutcome } from '../ports.js';
-export function GoalDialog(props: {
+export interface GoalDialogProps {
/** The Session to arm. `undefined` closes the dialog. */
sessionId?: string;
+ onArm(sessionId: string, request: GoalArmInput): Promise<GoalArmOutcome>;
onClose(): void;
-}) {
+}
+
+export function GoalDialog(props: GoalDialogProps) {
const locale = useUiLocale();
const copy = getShellCopy(locale).goalDialog;
const [condition, setCondition] = useState('');
@@ -106,8 +87,15 @@ export function GoalDialog(props: {
}, [props.sessionId]);
const sessionId = props.sessionId;
- const maxIterations = readGoalBudget(maxIterationsText, 1, GOAL_MAX_ITERATIONS_LIMIT);
- const tokenBudget = readGoalBudget(tokenBudgetText, GOAL_TOKEN_BUDGET_MINIMUM);
+ const maxIterations = readGoalBudget(
+ maxIterationsText,
+ 1,
+ GOAL_MAX_ITERATIONS_LIMIT,
+ );
+ const tokenBudget = readGoalBudget(
+ tokenBudgetText,
+ GOAL_TOKEN_BUDGET_MINIMUM,
+ );
const locked = reconciliation !== undefined;
const canSubmit =
condition.trim().length > 0 &&
@@ -142,9 +130,10 @@ export function GoalDialog(props: {
setArming(true);
setError(undefined);
try {
- const outcome = await window.maka.goal.arm(sessionId, {
+ const outcome = await props.onArm(sessionId, {
condition: condition.trim(),
- maxIterations: maxIterations.kind === 'value' ? maxIterations.value : null,
+ maxIterations:
+ maxIterations.kind === 'value' ? maxIterations.value : null,
tokenBudget: tokenBudget.kind === 'value' ? tokenBudget.value : null,
});
if (armGenerationRef.current !== armGeneration) return;
@@ -173,15 +162,24 @@ export function GoalDialog(props: {
className="goalDialog"
>
<Layout
- header={<DialogHeader title={copy.title} onOpenChange={(open) => {
- if (!open && !arming) props.onClose();
- }} />}
+ header={
+ <DialogHeader
+ title={copy.title}
+ onOpenChange={(open) => {
+ if (!open && !arming) props.onClose();
+ }}
+ />
+ }
content={
<LayoutContent padding={4}>
<VStack gap={4}>
- <Text type="body" color="secondary">{copy.description}</Text>
+ <Text type="body" color="secondary">
+ {copy.description}
+ </Text>
{reconciliationMessage ? (
- <Text type="body" color="secondary">{reconciliationMessage}</Text>
+ <Text type="body" color="secondary">
+ {reconciliationMessage}
+ </Text>
) : null}
<TextArea
label={copy.conditionLabel}
@@ -194,7 +192,9 @@ export function GoalDialog(props: {
isRequired
isDisabled={arming || locked}
hasAutoFocus
- {...(error ? { status: { type: 'error' as const, message: error } } : {})}
+ {...(error
+ ? { status: { type: 'error' as const, message: error } }
+ : {})}
/>
<HStack gap={3}>
<TextInput
@@ -205,7 +205,14 @@ export function GoalDialog(props: {
isOptional
isDisabled={arming || locked}
{...(maxIterations.kind === 'invalid'
- ? { status: { type: 'error' as const, message: copy.maxIterationsInvalid(GOAL_MAX_ITERATIONS_LIMIT) } }
+ ? {
+ status: {
+ type: 'error' as const,
+ message: copy.maxIterationsInvalid(
+ GOAL_MAX_ITERATIONS_LIMIT,
+ ),
+ },
+ }
: {})}
/>
<TextInput
@@ -216,7 +223,14 @@ export function GoalDialog(props: {
isOptional
isDisabled={arming || locked}
{...(tokenBudget.kind === 'invalid'
- ? { status: { type: 'error' as const, message: copy.tokenBudgetInvalid(GOAL_TOKEN_BUDGET_MINIMUM) } }
+ ? {
+ status: {
+ type: 'error' as const,
+ message: copy.tokenBudgetInvalid(
+ GOAL_TOKEN_BUDGET_MINIMUM,
+ ),
+ },
+ }
: {})}
/>
</HStack>
diff --git a/apps/desktop/src/renderer/features/goals/ui/goal-host.tsx b/apps/desktop/src/renderer/features/goals/ui/goal-host.tsx
new file mode 100644
index 000000000..f2e929e7e
--- /dev/null
+++ b/apps/desktop/src/renderer/features/goals/ui/goal-host.tsx
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { GoalArmInput, GoalArmOutcome } from '../ports.js';
+import { GoalDialog } from './goal-dialog.js';
+
+export interface GoalHostModel {
+ dialogSessionId?: string;
+ arm(sessionId: string, request: GoalArmInput): Promise<GoalArmOutcome>;
+ closeDialog(): void;
+}
+
+export function GoalHost({ model }: { model: GoalHostModel }) {
+ return (
+ <GoalDialog
+ {...(model.dialogSessionId
+ ? { sessionId: model.dialogSessionId }
+ : {})}
+ onArm={model.arm}
+ onClose={model.closeDialog}
+ />
+ );
+}
diff --git a/apps/desktop/src/renderer/main.tsx b/apps/desktop/src/renderer/main.tsx
index e994b4dc8..c7f267ed9 100644
--- a/apps/desktop/src/renderer/main.tsx
+++ b/apps/desktop/src/renderer/main.tsx
@@ -26,6 +26,8 @@ import './styles.css';
import { readSystemUiLocale } from './use-system-ui-locale';
import { WorkbarServicesProvider } from './features/workbar';
import { createDesktopWorkbarServices } from './platform/desktop/create-workbar-services';
+import { GoalServicesProvider } from './features/goals';
+import { createDesktopGoalServices } from './platform/desktop/create-goal-services';
const ONBOARDING_SNAPSHOT_RETRY_DELAY_MS = 150;
const ONBOARDING_SNAPSHOT_TIMEOUT_MS = 2_500;
@@ -33,6 +35,7 @@ const ONBOARDING_SNAPSHOT_TIMEOUT_MS = 2_500;
syncUiLocaleDocument(readSystemUiLocale());
applyCachedThemeBeforeMount();
const workbarServices = createDesktopWorkbarServices();
+const goalServices = createDesktopGoalServices();
/**
* Prefetch the onboarding snapshot BEFORE mounting React. The preload
@@ -65,8 +68,10 @@ async function prefetchOnboardingSnapshot(): Promise<OnboardingSnapshot | null>
void prefetchOnboardingSnapshot().then((initialOnboardingSnapshot) => {
createRoot(document.getElementById('root')!).render(
- <WorkbarServicesProvider services={workbarServices}>
- <App initialOnboardingSnapshot={initialOnboardingSnapshot} />
- </WorkbarServicesProvider>,
+ <GoalServicesProvider services={goalServices}>
+ <WorkbarServicesProvider services={workbarServices}>
+ <App initialOnboardingSnapshot={initialOnboardingSnapshot} />
+ </WorkbarServicesProvider>
+ </GoalServicesProvider>,
);
});
diff --git a/apps/desktop/src/renderer/platform/desktop/create-goal-services.ts b/apps/desktop/src/renderer/platform/desktop/create-goal-services.ts
new file mode 100644
index 000000000..c20768301
--- /dev/null
+++ b/apps/desktop/src/renderer/platform/desktop/create-goal-services.ts
@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { MakaBridge } from '../../../preload/bridge-contract.js';
+import type { GoalServices } from '../../features/goals';
+
+export type DesktopGoalBridge = Pick<MakaBridge, 'goal' | 'sessions'>;
+
+/** The only Desktop-to-Goals adapter. */
+export function createDesktopGoalServices(
+ bridge: DesktopGoalBridge = window.maka,
+): GoalServices {
+ return {
+ goal: {
+ get: (sessionId) => bridge.goal.get(sessionId),
+ arm: (sessionId, request) => bridge.goal.arm(sessionId, request),
+ clear: (sessionId) => bridge.goal.clear(sessionId),
+ pause: (sessionId) => bridge.goal.pause(sessionId),
+ resume: (sessionId) => bridge.goal.resume(sessionId),
+ subscribeChanges: (handler) =>
+ bridge.sessions.subscribeChanges((event) => {
+ if (event.reason === 'goal-change') handler(event.sessionId);
+ }),
+ },
+ };
+}
diff --git a/apps/desktop/src/renderer/use-session-goal.ts b/apps/desktop/src/renderer/use-session-goal.ts
deleted file mode 100644
index 6cfcaf53a..000000000
--- a/apps/desktop/src/renderer/use-session-goal.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-/**
- * Active-goal subscription for the renderer — the desktop kill-switch data source.
- *
- * Reads the session's goal via the preload bridge and re-fetches whenever the
- * main process emits a `goal-change` session event (goal set / continue /
- * pause / resume / terminal / clear). Only surfaces goals that are still
- * running (active or waiting, or paused); a settled goal returns null so the
- * session context disappears.
- *
- * Kept as a tiny standalone hook (no app-shell coupling) so an autonomous,
- * token-burning loop always has a visible indicator and a one-click stop,
- * regardless of where the chat surface renders it.
- */
-import { useEffect, useState } from 'react';
-import type { GoalState, GoalStatus } from '@maka/runtime/goal-state';
-
-type LiveGoalStatus = Extract<GoalStatus, 'active' | 'waiting'>;
-type LiveGoalState =
- | (GoalState & { readonly status: LiveGoalStatus })
- | (GoalState & { readonly status: 'paused'; readonly pausedAt: number });
-
-const LIVE_GOAL_STATUSES: ReadonlySet<GoalStatus> = new Set(['active', 'waiting', 'paused']);
-
-function isLiveGoal(goal: GoalState): goal is LiveGoalState {
- return (
- LIVE_GOAL_STATUSES.has(goal.status) &&
- (goal.status !== 'paused' ||
- (typeof goal.pausedAt === 'number' && Number.isFinite(goal.pausedAt)))
- );
-}
-
-export function useSessionGoal(sessionId: string | undefined): LiveGoalState | null {
- const [goal, setGoal] = useState<LiveGoalState | null>(null);
-
- useEffect(() => {
- if (!sessionId) {
- setGoal(null);
- return;
- }
- // The previous Session's Goal is not an answer for this one, so it goes
- // before the first fetch resolves rather than after.
- setGoal(null);
- let cancelled = false;
- let refreshSequence = 0;
- const refresh = (): void => {
- const sequence = ++refreshSequence;
- void window.maka.goal
- .get(sessionId)
- .then((g) => {
- if (cancelled || sequence !== refreshSequence) return;
- setGoal(g && isLiveGoal(g) ? g : null);
- })
- .catch(() => {
- if (!cancelled && sequence === refreshSequence) setGoal(null);
- });
- };
- refresh();
- const unsubscribe = window.maka.sessions.subscribeChanges((event) => {
- // Refetch on goal transitions for this session (an undefined sessionId on
- // the event is a broadcast — refetch to be safe).
- if (event.reason === 'goal-change' && (!event.sessionId || event.sessionId === sessionId)) {
- refresh();
- }
- });
- return () => {
- cancelled = true;
- refreshSequence += 1;
- unsubscribe();
- };
- }, [sessionId]);
-
- return goal;
-}
diff --git a/apps/desktop/stories/app-shell.stories.tsx b/apps/desktop/stories/app-shell.stories.tsx
index 838f100f6..f10c8d958 100644
--- a/apps/desktop/stories/app-shell.stories.tsx
+++ b/apps/desktop/stories/app-shell.stories.tsx
@@ -39,7 +39,7 @@ import { deriveBranchBanner } from '../src/renderer/branch-banner';
import { deriveSessionRevisionNavigation } from '../src/renderer/session-revisions';
import { deriveSessionRail } from '../src/renderer/session-rail';
import { AppShell as AstryxAppShell } from '@astryxdesign/core/AppShell';
-import { GoalDialog } from '../src/renderer/goal-dialog';
+import { GoalDialog } from '../src/renderer/features/goals/testing';
const NOW = Date.UTC(2026, 6, 1, 9, 30, 0);
@@ -1126,7 +1126,28 @@ export const GoalDialogOpen: Story = {
render: () => (
<>
<ComposedShell />
- <GoalDialog sessionId="session-1" onClose={noop} />
+ <GoalDialog
+ sessionId="session-1"
+ onArm={async () => ({
+ kind: 'armed',
+ goal: {
+ id: 'storybook-goal',
+ revision: 1,
+ sessionId: 'storybook-session',
+ condition: 'Ship the Storybook example',
+ status: 'active',
+ setAt: Date.now(),
+ iterations: 0,
+ maxIterations: 25,
+ consecutiveNoProgress: 0,
+ blockCap: 8,
+ tokensAtStart: 0,
+ tokensNow: 0,
+ tokensBaselinePending: false,
+ },
+ })}
+ onClose={noop}
+ />
</>
),
};
diff --git a/docs/astryx-surface-file-inventory.md b/docs/astryx-surface-file-inventory.md
index 3b38a009d..3544e3cde 100644
--- a/docs/astryx-surface-file-inventory.md
+++ b/docs/astryx-surface-file-inventory.md
@@ -38,6 +38,9 @@ Wiki bar: Design Conventions · API Use-the-System · Theming · Container Paddi
| `apps/desktop/src/renderer/command-palette.tsx` | dialog-overlay | EmptyState | aligned — uses Astryx (EmptyState) | aligned |
| `apps/desktop/src/renderer/custom-pet-companion.tsx` | other | none | aligned — no raw controls; no Astryx JSX usage | aligned |
| `apps/desktop/src/renderer/error-boundary.tsx` | other | Button, Card | aligned — uses Astryx (Button, Card) | aligned |
+| `apps/desktop/src/renderer/features/goals/services-context.tsx` | other | none | aligned — no raw controls; no Astryx JSX usage | aligned |
+| `apps/desktop/src/renderer/features/goals/ui/goal-dialog.tsx` | dialog-overlay | Button, Dialog, DialogHeader, HStack, Layout, LayoutContent, Text, TextInput, VStack | aligned — uses Astryx (Button, Dialog, DialogHeader, HStack, Layout, LayoutContent, Text, TextInput) | aligned |
+| `apps/desktop/src/renderer/features/goals/ui/goal-host.tsx` | other | none | aligned — no raw controls; no Astryx JSX usage | aligned |
| `apps/desktop/src/renderer/features/workbar/services-context.tsx` | shell-chrome-or-panel | none | aligned — no raw controls; no Astryx JSX usage | aligned |
| `apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-pane.tsx` | shell-chrome-or-panel | Badge, Banner, Button, EmptyState | aligned — uses Astryx (Badge, Banner, Button, EmptyState) | aligned |
| `apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview-registry-shell.tsx` | shell-chrome-or-panel | Banner, Button, Spinner | aligned — uses Astryx (Banner, Button, Spinner) | aligned |
@@ -51,7 +54,6 @@ Wiki bar: Design Conventions · API Use-the-System · Theming · Container Paddi
| `apps/desktop/src/renderer/features/workbar/ui/workbar-host.tsx` | shell-chrome-or-panel | Card, ResizeHandle, Spinner | aligned — uses Astryx (Card, ResizeHandle, Spinner) | aligned |
| `apps/desktop/src/renderer/features/workbar/ui/workbar-surface.tsx` | shell-chrome-or-panel | Badge, Button, Card, ContextMenu, Heading, IconButton, List, ListItem, Section, Spinner, Tooltip | aligned — uses Astryx (Badge, Button, Card, ContextMenu, Heading, IconButton, List, ListItem) | aligned |
| `apps/desktop/src/renderer/features/workbar/ui/workbar-toggle.tsx` | shell-chrome-or-panel | IconButton, Tooltip | aligned — uses Astryx (IconButton, Tooltip) | aligned |
-| `apps/desktop/src/renderer/goal-dialog.tsx` | dialog-overlay | Button, Dialog, DialogHeader, HStack, Layout, LayoutContent, Text, TextInput, VStack | aligned — uses Astryx (Button, Dialog, DialogHeader, HStack, Layout, LayoutContent, Text, TextInput) | aligned |
| `apps/desktop/src/renderer/keyboard-help.tsx` | dialog-overlay | Dialog, DialogHeader, Heading, Layout, LayoutContent | aligned — uses Astryx (Dialog, DialogHeader, Heading, Layout, LayoutContent) | aligned |
| `apps/desktop/src/renderer/live-turn-reconciler.tsx` | other | none | aligned — no raw controls; no Astryx JSX usage | aligned |
| `apps/desktop/src/renderer/maka-tokens.css` | styles | n/a (css) | aligned — no off-rhythm control heights flagged | aligned |
diff --git a/docs/astryx-surface-file-inventory.paths b/docs/astryx-surface-file-inventory.paths
index e612562a0..fc5720ad9 100644
--- a/docs/astryx-surface-file-inventory.paths
+++ b/docs/astryx-surface-file-inventory.paths
@@ -10,6 +10,9 @@ apps/desktop/src/renderer/chat-message-surface.tsx
apps/desktop/src/renderer/command-palette.tsx
apps/desktop/src/renderer/custom-pet-companion.tsx
apps/desktop/src/renderer/error-boundary.tsx
+apps/desktop/src/renderer/features/goals/services-context.tsx
+apps/desktop/src/renderer/features/goals/ui/goal-dialog.tsx
+apps/desktop/src/renderer/features/goals/ui/goal-host.tsx
apps/desktop/src/renderer/features/workbar/services-context.tsx
apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-pane.tsx
apps/desktop/src/renderer/features/workbar/tools/artifacts/artifact-preview-registry-shell.tsx
@@ -23,7 +26,6 @@ apps/desktop/src/renderer/features/workbar/ui/side-chat-close-confirmation.tsx
apps/desktop/src/renderer/features/workbar/ui/workbar-host.tsx
apps/desktop/src/renderer/features/workbar/ui/workbar-surface.tsx
apps/desktop/src/renderer/features/workbar/ui/workbar-toggle.tsx
-apps/desktop/src/renderer/goal-dialog.tsx
apps/desktop/src/renderer/keyboard-help.tsx
apps/desktop/src/renderer/live-turn-reconciler.tsx
apps/desktop/src/renderer/maka-tokens.css
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org