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