@melite/estate-call 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,57 @@
+---
+description: The one lane-call contract and card-tool builder — transport, flow-envelope output schema, and the executor test battery shared by every card tool.
+kind: package-library
+---
+
+# @melite/estate-call
+
+`@melite/estate-call` is the SSOT for card-tool mechanics: the lane-call
+contract (JSON in/out, cancellation, named refusals), the flow-envelope
+output schema, and the executor test battery. It calls no engine — the
+tools plane hands each card a transport built from the ctx seats,
+in-process, no HTTP and no gateway. Card packages and
+`@melite/harness-tools` compose it; its six-per-card predecessor copies are
+the degeneration this package absorbed.
+
+## Contract
+
+- `.` — `EstateCall` (the structural transport), `GatewayError` (status +
+  body + named `error` field), `jsonLane` (adapts the raw call to the
+  JSON-record contract; a pre-aborted call never dials).
+- `./cardTool` — `defineCardTool(call, spec)`: owns the `CARD_TOOL_OUTPUT`
+  envelope (flow, model, run_id, draft_id, status, error), declared
+  JSON-array param normalization, the two-door execute (drafts, then start
+  with the `{model:}` lift), refusal mapping, and the presentation
+  projections. The card still owns its tool-plane name, flow id, identity
+  prose, emitted params spec, and default model.
+- `./executorHarness` — `executorHarness` + `registerExecutorBattery`: the
+  recording seam, envelope arms, tile truth table, and presenter cores the
+  per-card specs restate.
+- `./package.json`.
+
+## Model Experience
+
+### Request context and condition
+
+#### What the model sees
+
+The card tool's face — identity prose and emitted params spec — rides the
+host toolset schemas, and the returned flow envelope is the tool result;
+both are model-visible and logged by the session.
+
+#### Token effect
+
+Conditional — scales with the params spec and the envelope the run returns.
+
+#### KV Cache effect
+
+Append-only — each card-tool call and its result append to the session
+transcript.
+
+## Known Limitations and Deferred Work
+
+- **One flow per call** — the builder starts exactly one run and returns
+  its envelope; polling the run is the caller's job (run_status).
+- **Refusals are field-named, not typed** — `GatewayError` carries the
+  door's refusal word in a named field; there is no closed refusal union at
+  this seam.

package/lib/cardTool.d.ts

@@ -59,9 +59,9 @@ export interface CardToolSpec {
     /** Resolve a served model value to the estate's admission
      *  spelling before it crosses the wire. Cards serving the
      *  semantic style enum close over their own entries (the fold
-     * at comfyui-cordis/semanticModelKnob.ts — one spelling); cards
-     * serving bare family ids leave it unstated and the value
-     * crosses verbatim. */
+     * at comfyui-card-kit/src/semanticModelKnob.ts — one
+     *  spelling); cards serving bare family ids leave it unstated
+     *  and the value crosses verbatim. */
     resolveModel?: (value: string) => string;
     previewField?: string;
     previewValue?: (a: Record<string, unknown>) => string;

package/lib/cardTool.js

@@ -67,6 +67,15 @@ export function defineCardTool(call, spec) {
     const gw = jsonLane(call);
     const { name: TOOL_NAME, flow: FLOW, label, description, defaultModel: DEFAULT_MODEL, previewField, previewValue, timeoutMs } = spec;
     const previewPart = previewValue ?? ((a) => `${previewField}=${String(a[previewField] ?? '').slice(0, 60)}`);
+    
+
+
+
+
+
+
+
+    const resolveModelArg = (a) => typeof a.model === 'string' && a.model !== '' ? a.model : DEFAULT_MODEL;
     return defineTool({
         name: TOOL_NAME,
         description,
@@ -80,7 +89,7 @@ export function defineCardTool(call, spec) {
                 card: 'generic',
                 title: label,
                 kind: 'execute',
-                rawInput: `model=${String(a.model ?? DEFAULT_MODEL)} ${previewPart(a)}`,
+                rawInput: `model=${resolveModelArg(a)} ${previewPart(a)}`,
             };
         },
         output: {
@@ -138,7 +147,7 @@ export function defineCardTool(call, spec) {
             // spec.resolveModel first: the estate's admission spelling
             // (a route atom) crosses the wire, while the envelope and
             // preview keep the picked style value.
-            const rawModel = typeof a.model === 'string' && a.model !== '' ? a.model : DEFAULT_MODEL;
+            const rawModel = resolveModelArg(a);
             const model = spec.resolveModel !== undefined ? spec.resolveModel(rawModel) : rawModel;
             const params = {};
             for (const [k, v] of Object.entries(a))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melite/estate-call",
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "license": "SSPL-1.0",
   "type": "module",
   "exports": {