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/26 14:58:08 UTC
(maka) 17/26: refactor: narrow two Message admission shapes to what reads them
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch fix/canonical-message-projection
in repository https://gitbox.apache.org/repos/asf/maka.git
commit 53b52bc8449fb1afb1a8a0dadb590854be5357b7
Author: AstroHan <le...@outlook.com>
AuthorDate: Wed Aug 26 12:59:06 2026 +0800
refactor: narrow two Message admission shapes to what reads them
Two carriers outlived the readers they were shaped for.
`readCancelledMessageAdmission` returned the tombstone's digest and
placement, but its only production caller asks one thing: is this Message
identity cancelled. The columns never left the storage layer, and the
digest regex and placement validation existed to guard a payload nothing
consumed. It becomes `hasCancelledMessageAdmission`, reusing the existence
query the commit path already runs two functions above.
`SkillInvocationBlockedError` carried a `SkillInvocationResult` for a
`catch` that no longer exists — the CLI TUI now learns about a refused
invocation from the `blocked` submit disposition instead. The remaining
thrower is `preparePrompt`, whose only caller is headless `maka run`, and
that path reports the failure as an ordinary error without reading the
payload. So the reasons move into the message: `maka run` now says which
Skill could not be resolved and why, where before it said only that one
could not be.
Generated-by: Claude Code
---
packages/cli/src/__tests__/pi-tui-runner.test.ts | 23 +++++++-------
.../__tests__/runtime-host-session-driver.test.ts | 16 +++++-----
packages/cli/src/runtime-host-session-driver.ts | 7 +++--
packages/cli/src/session-driver.ts | 20 +++++++++---
.../src/__tests__/message-coordinator.test.ts | 12 ++------
.../runtime-host/src/server/message-coordinator.ts | 8 ++---
.../sqlite-session-metadata-store.test.ts | 7 ++---
packages/storage/src/execution-stores.ts | 4 +--
packages/storage/src/message-admission-store.ts | 16 ++++------
packages/storage/src/session-store.ts | 4 +--
.../storage/src/sqlite-session-metadata-store.ts | 36 +++-------------------
11 files changed, 60 insertions(+), 93 deletions(-)
diff --git a/packages/cli/src/__tests__/pi-tui-runner.test.ts b/packages/cli/src/__tests__/pi-tui-runner.test.ts
index 630608280..503ea6deb 100644
--- a/packages/cli/src/__tests__/pi-tui-runner.test.ts
+++ b/packages/cli/src/__tests__/pi-tui-runner.test.ts
@@ -56,7 +56,7 @@ import type {
RewindTarget,
SessionResumeAvailability,
} from '../session-driver.js';
-import { SkillInvocationBlockedError } from '../session-driver.js';
+import { skillInvocationBlockedMessage } from '../session-driver.js';
import { listApiKeyOnboardableProviders } from '../onboarding-catalog.js';
import type {
MakaOnboardingSurface,
@@ -7769,29 +7769,28 @@ class HostSkillDriver extends SlashCommandDriver {
super();
}
+ /** Nothing the Host could resolve, so it opens no Turn for this Message. */
+ #refuses(): boolean {
+ return this.skillInvocation.loaded.length === 0 && this.skillInvocation.failed.length > 0;
+ }
+
// The Host answers a refused invocation with a `blocked` disposition rather
- // than a Turn; the driver surfaces that as the submit result.
+ // than a Turn; the driver hands that back as the submit result.
override async submitMessage(
text: string,
options: MakaSubmitMessageOptions,
): Promise<TurnMessageSubmitResult | undefined> {
- try {
- return await super.submitMessage(text, options);
- } catch (error) {
- if (error instanceof SkillInvocationBlockedError) {
- return { disposition: 'blocked', skillInvocation: error.skillInvocation };
- }
- throw error;
+ if (this.#refuses()) {
+ return { disposition: 'blocked', skillInvocation: this.skillInvocation };
}
+ return super.submitMessage(text, options);
}
override async preparePrompt(
prompt: string,
options: MakaPreparePromptOptions = {},
): Promise<MakaPreparedSessionTurn> {
- if (this.skillInvocation.loaded.length === 0 && this.skillInvocation.failed.length > 0) {
- throw new SkillInvocationBlockedError(this.skillInvocation);
- }
+ if (this.#refuses()) throw new Error(skillInvocationBlockedMessage(this.skillInvocation));
const turn = await super.preparePrompt(prompt, options);
return { ...turn, skillInvocation: this.skillInvocation };
}
diff --git a/packages/cli/src/__tests__/runtime-host-session-driver.test.ts b/packages/cli/src/__tests__/runtime-host-session-driver.test.ts
index 70687991a..683634557 100644
--- a/packages/cli/src/__tests__/runtime-host-session-driver.test.ts
+++ b/packages/cli/src/__tests__/runtime-host-session-driver.test.ts
@@ -48,10 +48,9 @@ import {
createRuntimeHostMakaSessionDriver,
type RuntimeHostMakaSessionDriverInput,
} from '../runtime-host-session-driver.js';
-import {
- SkillInvocationBlockedError,
- type MakaAttachedSessionTurn,
- type MakaSideConversationParentStatus,
+import type {
+ MakaAttachedSessionTurn,
+ MakaSideConversationParentStatus,
} from '../session-driver.js';
import { WAIT_BUDGET_MS } from './tui-terminal-mock.js';
@@ -1529,10 +1528,11 @@ describe('Runtime Host Maka Session driver', () => {
assert.equal(connection.requests.at(-1)?.operation, 'turn.start');
connection.skillStartBlocked = true;
- await assert.rejects(
- driver.preparePrompt('/skill:missing', { turnId: 'turn-blocked' }),
- SkillInvocationBlockedError,
- );
+ // The failure names what could not be resolved: headless `maka run` reports
+ // this message and nothing reads a structured payload off it.
+ await assert.rejects(driver.preparePrompt('/skill:missing', { turnId: 'turn-blocked' }), {
+ message: /Could not resolve the Skill this Turn asked for: \/skill:missing \(not found\)/,
+ });
});
test('retires a pending question when another client answers it', async () => {
diff --git a/packages/cli/src/runtime-host-session-driver.ts b/packages/cli/src/runtime-host-session-driver.ts
index 33454b3b7..53143fa06 100644
--- a/packages/cli/src/runtime-host-session-driver.ts
+++ b/packages/cli/src/runtime-host-session-driver.ts
@@ -96,7 +96,10 @@ import type {
RewindTarget,
SessionResumeAvailability,
} from './session-driver.js';
-import { inspectSessionResumeAvailability, SkillInvocationBlockedError } from './session-driver.js';
+import {
+ inspectSessionResumeAvailability,
+ skillInvocationBlockedMessage,
+} from './session-driver.js';
import {
cwdRank,
firstLine,
@@ -327,7 +330,7 @@ class RuntimeHostMakaSessionDriverImpl implements RuntimeHostMakaSessionDriver {
};
const result = await this.#connection.request('turn.start', startInput);
if (result.kind === 'blocked') {
- throw new SkillInvocationBlockedError(result.skillInvocation);
+ throw new Error(skillInvocationBlockedMessage(result.skillInvocation));
}
const started = result.turn;
const skillInvocation =
diff --git a/packages/cli/src/session-driver.ts b/packages/cli/src/session-driver.ts
index 96e098a54..ed7534e21 100644
--- a/packages/cli/src/session-driver.ts
+++ b/packages/cli/src/session-driver.ts
@@ -116,11 +116,21 @@ export interface MakaRetractedMessages {
messageIds: readonly string[];
}
-export class SkillInvocationBlockedError extends Error {
- constructor(readonly skillInvocation: SkillInvocationResult) {
- super('Explicit Skill invocation could not be resolved');
- this.name = 'SkillInvocationBlockedError';
- }
+/**
+ * Why Runtime Host refused to open a Turn for an explicit Skill invocation.
+ * `turn.start`'s only remaining caller is headless `maka run`, which reports
+ * this as an ordinary failure, so the reasons belong in the message rather
+ * than in a payload nothing reads.
+ */
+export function skillInvocationBlockedMessage(skillInvocation: SkillInvocationResult): string {
+ const reasons = skillInvocation.failed.map((failure) =>
+ failure.reason === 'too_many_requests'
+ ? `more than ${failure.requestLimit} Skill requests`
+ : `/skill:${failure.request} (${failure.reason.replaceAll('_', ' ')})`,
+ );
+ return reasons.length > 0
+ ? `Could not resolve the Skill this Turn asked for: ${reasons.join(', ')}`
+ : 'Explicit Skill invocation could not be resolved';
}
export interface MakaSessionDriver {
diff --git a/packages/runtime-host/src/__tests__/message-coordinator.test.ts b/packages/runtime-host/src/__tests__/message-coordinator.test.ts
index f255b59ca..4ac57c931 100644
--- a/packages/runtime-host/src/__tests__/message-coordinator.test.ts
+++ b/packages/runtime-host/src/__tests__/message-coordinator.test.ts
@@ -2297,16 +2297,8 @@ function memoryMessageAdmissionStore(
return admission;
},
readMessageAdmission: async (_sessionId, messageId) => admissions.get(messageId)?.admission,
- readCancelledMessageAdmission: async (_sessionId, messageId) => {
- const entry = admissions.get(messageId);
- return entry?.state === 'cancelled'
- ? {
- messageId,
- submittedContentDigest: entry.admission.submittedContentDigest,
- submittedPlacement: entry.admission.submittedPlacement,
- }
- : undefined;
- },
+ hasCancelledMessageAdmission: async (_sessionId, messageId) =>
+ admissions.get(messageId)?.state === 'cancelled',
listMessageAdmissions: async (sessionId) =>
[...admissions.values()]
.filter(({ admission, state }) => admission.sessionId === sessionId && state === 'accepted')
diff --git a/packages/runtime-host/src/server/message-coordinator.ts b/packages/runtime-host/src/server/message-coordinator.ts
index 0575d4201..c21b121f9 100644
--- a/packages/runtime-host/src/server/message-coordinator.ts
+++ b/packages/runtime-host/src/server/message-coordinator.ts
@@ -395,11 +395,9 @@ export class HostMessageCoordinator implements RuntimeMessageAuthority {
}): Promise<MessageOutcome<{ cancelledMessageIds: string[] }>> {
const cancelledMessageIds: string[] = [];
for (const messageId of input.messageIds) {
- const cancelled = await this.#admissions.readCancelledMessageAdmission(
- input.sessionId,
- messageId,
- );
- if (cancelled) cancelledMessageIds.push(messageId);
+ if (await this.#admissions.hasCancelledMessageAdmission(input.sessionId, messageId)) {
+ cancelledMessageIds.push(messageId);
+ }
}
return success({ cancelledMessageIds });
}
diff --git a/packages/storage/src/__tests__/sqlite-session-metadata-store.test.ts b/packages/storage/src/__tests__/sqlite-session-metadata-store.test.ts
index 93027587f..f0b771fd5 100644
--- a/packages/storage/src/__tests__/sqlite-session-metadata-store.test.ts
+++ b/packages/storage/src/__tests__/sqlite-session-metadata-store.test.ts
@@ -445,11 +445,8 @@ describe('SqliteSessionMetadataStore', () => {
await store.commitMessageAdmission(admission);
await store.cancelMessageAdmissions('session-1', ['message-1']);
assert.deepEqual(await store.listMessageAdmissions('session-1'), []);
- assert.deepEqual(await store.readCancelledMessageAdmission('session-1', 'message-1'), {
- messageId: 'message-1',
- submittedContentDigest: messageContentDigest({ text: 'discard this draft' }),
- submittedPlacement: 'next_turn',
- });
+ assert.equal(await store.hasCancelledMessageAdmission('session-1', 'message-1'), true);
+ assert.equal(await store.hasCancelledMessageAdmission('session-1', 'message-2'), false);
await assert.rejects(
store.commitMessageAdmission(admission),
/identity is already cancelled/,
diff --git a/packages/storage/src/execution-stores.ts b/packages/storage/src/execution-stores.ts
index 88201cf48..bd9dbe67e 100644
--- a/packages/storage/src/execution-stores.ts
+++ b/packages/storage/src/execution-stores.ts
@@ -415,8 +415,8 @@ async function createExecutionStoresForWrite<K extends StorageRootKind, E extend
run(() => sessionStore.commitMessageAdmission(admission)),
readMessageAdmission: (sessionId, messageId) =>
run(() => sessionStore.readMessageAdmission(sessionId, messageId)),
- readCancelledMessageAdmission: (sessionId, messageId) =>
- run(() => sessionStore.readCancelledMessageAdmission(sessionId, messageId)),
+ hasCancelledMessageAdmission: (sessionId, messageId) =>
+ run(() => sessionStore.hasCancelledMessageAdmission(sessionId, messageId)),
listMessageAdmissions: (sessionId) =>
run(() => sessionStore.listMessageAdmissions(sessionId)),
markMessagesHandedOff: (input) => run(() => sessionStore.markMessagesHandedOff(input)),
diff --git a/packages/storage/src/message-admission-store.ts b/packages/storage/src/message-admission-store.ts
index e0b728e10..25fe352c7 100644
--- a/packages/storage/src/message-admission-store.ts
+++ b/packages/storage/src/message-admission-store.ts
@@ -35,22 +35,18 @@ export interface PendingMessageAdmission {
readonly admittedAt: number;
}
-export interface CancelledMessageAdmission {
- readonly messageId: string;
- readonly submittedContentDigest: `sha256:${string}`;
- readonly submittedPlacement: 'current_turn' | 'next_turn';
-}
-
export interface MessageAdmissionStore {
commitMessageAdmission(admission: PendingMessageAdmission): Promise<PendingMessageAdmission>;
readMessageAdmission(
sessionId: string,
messageId: string,
): Promise<PendingMessageAdmission | undefined>;
- readCancelledMessageAdmission(
- sessionId: string,
- messageId: string,
- ): Promise<CancelledMessageAdmission | undefined>;
+ /**
+ * Whether this Message identity carries a cancellation tombstone. That a
+ * Message was cancelled is the whole fact callers need — the tombstone's
+ * own columns never leave this layer.
+ */
+ hasCancelledMessageAdmission(sessionId: string, messageId: string): Promise<boolean>;
listMessageAdmissions(sessionId: string): Promise<readonly PendingMessageAdmission[]>;
markMessagesHandedOff(input: {
sessionId: string;
diff --git a/packages/storage/src/session-store.ts b/packages/storage/src/session-store.ts
index 3d69a5267..10d045a4d 100644
--- a/packages/storage/src/session-store.ts
+++ b/packages/storage/src/session-store.ts
@@ -888,9 +888,9 @@ class SqliteSessionStore implements SessionAuthorityStore {
return this.metadata.readMessageAdmission(sessionId, messageId);
}
- async readCancelledMessageAdmission(sessionId: string, messageId: string) {
+ async hasCancelledMessageAdmission(sessionId: string, messageId: string): Promise<boolean> {
await this.ensureReady();
- return this.metadata.readCancelledMessageAdmission(sessionId, messageId);
+ return this.metadata.hasCancelledMessageAdmission(sessionId, messageId);
}
async listMessageAdmissions(sessionId: string): Promise<readonly PendingMessageAdmission[]> {
diff --git a/packages/storage/src/sqlite-session-metadata-store.ts b/packages/storage/src/sqlite-session-metadata-store.ts
index a2ed11dfc..8eb75134a 100644
--- a/packages/storage/src/sqlite-session-metadata-store.ts
+++ b/packages/storage/src/sqlite-session-metadata-store.ts
@@ -1656,45 +1656,17 @@ export class SqliteSessionMetadataStore {
});
}
- async readCancelledMessageAdmission(
- sessionId: string,
- messageId: string,
- ): Promise<
- | {
- messageId: string;
- submittedContentDigest: `sha256:${string}`;
- submittedPlacement: 'current_turn' | 'next_turn';
- }
- | undefined
- > {
+ async hasCancelledMessageAdmission(sessionId: string, messageId: string): Promise<boolean> {
this.assertOpen();
assertSafeSessionId(sessionId);
assertSafeSessionId(messageId);
return this.readTransaction(() => {
const row = this.db
.prepare(
- `
- SELECT submitted_content_digest, submitted_placement
- FROM cancelled_message_admissions
- WHERE session_id = ? AND message_id = ?
- `,
+ 'SELECT 1 AS present FROM cancelled_message_admissions WHERE session_id = ? AND message_id = ?',
)
- .get(sessionId, messageId) as
- | { submitted_content_digest?: unknown; submitted_placement?: unknown }
- | undefined;
- if (!row) return undefined;
- if (
- typeof row.submitted_content_digest !== 'string' ||
- !/^sha256:[a-f0-9]{64}$/u.test(row.submitted_content_digest) ||
- (row.submitted_placement !== 'current_turn' && row.submitted_placement !== 'next_turn')
- ) {
- throw new SessionMetadataConflictError('Invalid cancelled Message admission identity');
- }
- return {
- messageId,
- submittedContentDigest: row.submitted_content_digest as `sha256:${string}`,
- submittedPlacement: row.submitted_placement,
- };
+ .get(sessionId, messageId);
+ return row !== undefined;
});
}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org