Capabilities & Gaps

The capability matrix, the honest gaps, and why a false flag does not mean a missing feature.

A capability flag describes what an engine can report, not what it can do.

import { PRAISONAI_TS_CAPABILITIES } from "praisonai-mobile/engines/praisonai-ts";

if (PRAISONAI_TS_CAPABILITIES.tools) renderToolRows();

Quick Start

1. Read a capability before rendering

   const caps = engine.capabilities;

   Capabilities are a property, so the UI decides what to render before the first token.

2. Print the unsupported scenarios

   npm run test

   The conformance suite prints every scenario an engine cannot produce.

The Capability Matrix

What each shipped engine can report.

Closed Gaps

The rows kept from the old gap report so a reader arriving from an old bug can find where they went.

Open Gaps

Known-open, stated rather than implied so a follow-up author can pick them up.

Reported, not fixed

The capabilities PR #4794 audited but deliberately left unwired, named here so a follow-up author can pick them up.

Why tools: false For praisonai-ts

praisonai-ts executes tools normally; it just never announces them. Upstream Agent.streamEvents() emits a three-variant union — text, finish, error — and none of those carry a tool call, so the engine cannot report one.

type AgentEvent =
  | { type: "text";   delta: string }
  | { type: "finish"; text: string }
  | { type: "error";  error: Error };

The flag describes what the engine can report. A UI that renders tool rows off a true flag would render nothing and look broken — and a tool call that silently failed would be indistinguishable from a normal answer, which is exactly what tool_result.ok was introduced to prevent.

How Each Gap Closed

Gap 4 was “mechanism landed, not wired”: createSession was called and RunPersistence.record was called, and nothing connected them — the two signatures did not even line up (record(prompt, answer) against record(request, answer)).

// The named adapter where the two vocabularies meet.
export function persistenceFor(session: Session) {
  return { record: (request, answer) => session.record(request.prompt, answer) };
}

Gap 5 was “property added, snapshot not seeded”: keyboardHeightPx was declared = 0 and only updated by an event, so a component mounting while the keyboard was already up laid out at 0 for one frame and then jumped.

let keyboardHeightPx = readKeyboardHeight(view); // seeded at construction

Both are verified by a positive control: reverting either makes a named test fail.

Gap 6 was also “mechanism landed, not wired”: the Dropped type, the view-model row and the seven user-facing strings all existed with no producer. remote-http was the only production caller of decodeEvent and discarded every rejection, so a malformed frame made its tool vanish and the turn rendered as a clean answer.

// The channel between the engine and the controller, neither of which can
// call the other. Refusals are drained onto the transcript per event and
// again in finally, so one beside the last frame is still shown.
export function createDropSink(): DropSink { /* note + drain */ }

A carry field fixed the cross-turn contamination: apply(start) no longer carries the previous turn’s entire dropped list, so one refusal on turn 1 no longer paints every later turn as damaged. Two composition tests pin the two wiring hops — createApp and the real enginesFor — because removing the sink from createRunController or dropping the registry’s forward each left the suite green in isolation. See Dropped Events.

The Unsupported Scenario

From src/praisonai-mobile/docs/gaps.md, the one conformance scenario praisonai-ts still declares unsupported. Tool scenarios and the single-approval scenario are produced and passing since upstream gained tool_call/tool_result and the dead approval skip guard was retired in PraisonAI PR #4641.

Each is printed on every run, so a contract that quietly shrinks is visible rather than silently green.

approval runs because that case only asserts that deciding an unknown id returns false, which praisonai-ts‘s decide() always does — no approval channel needed. capabilities.approvals stays false because the engine still cannot emit an approval request, which is what two_approvals needs.

Roadmap

The in-process engine now ships and boots on a device: the mobile path imports praisonai/mobile — the package’s webview-safe entry (praisonai-ts #4720) — as a lazy chunk, and defaultEngineIdFor("tauri") returns praisonai-ts. The CLI-oriented agent/simple.ts still carries Node-only imports (crypto, and events in ai/tool-approval.ts), but those are not for the webview — the /mobile entry avoids them, so they no longer block the mobile app.

The remaining device gap is the API-key setting: the registry declares no secret setting yet, so a first turn reaches the model layer and fails recoverably for want of a key. A key setting is the tracked follow-up. See Engines → The known API-key gap.

Remaining native-shell gaps (tracked in src/praisonai-mobile/docs/gaps.md):

• keyboard-height is still never emitted natively; the TypeScript reads visualViewport and would take a native event as an override.
• iOS edge-swipe back is not installed.
• Haptics and share have no plugin; their bridge invokes reject and the bridge degrades.

See Native Shell for the events that now emit.

Best Practices

Related