@gencode/uni 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @gencode/uni
+
+## 0.2.0
+
+### Minor Changes
+
+- 26ad74d: Add a standalone `@gencode/uni` package for unified multi-agent runtime execution with provider selection, callback delivery, websocket streaming, and shared event normalization.
+
+### Patch Changes
+
+- 26ad74d: Normalize provider tool call events for Claude Code and OpenCode, and add uni runtime tool hooks for before/after tool call observability.
+
+## 0.1.0
+
+- Initial release placeholder.

package/README.md

@@ -0,0 +1,50 @@
+# @gencode/uni
+
+Independent unified agent runtime for AIMax.
+
+`@gencode/uni` does not reuse the existing `@gencode/cli` or `@gencode/agents`
+run pipeline. It provides:
+
+- `runUni()` for one-shot execution
+- pluggable runtime agents (`claude-code`, `codex`, `opencode`, `pi`, `acp`)
+- callback and websocket transports
+- a normalization layer that maps provider-native output to
+  `@gencode/shared` run events
+
+This package is intentionally standalone. Existing CLI integration remains a
+separate concern.
+
+## CLI
+
+`@gencode/uni` also exposes a standalone binary:
+
+```bash
+gencode-uni run \
+  --runtime-agent codex \
+  --data-dir /data/user1 \
+  --message "Review this repository" \
+  --runtime-cli-path "codex --proxy" \
+  --runtime-mode full-auto \
+  --runtime-provider-base-url https://relay.example.com/v1
+```
+
+The command keeps the current `aimax run` parameter surface for core fields and
+adds runtime-specific flags inspired by `reference/cc-connect`, such as:
+
+- `--runtime-cli-path`
+- `--runtime-cli-args-flag`
+- `--runtime-mode`
+- `--runtime-reasoning-effort`
+- `--runtime-router-url`
+- `--runtime-router-api-key`
+- `--runtime-codex-home`
+- `--runtime-provider-env`
+- `--runtime-provider-header`
+
+## Smoke Tests
+
+Provider-specific helper scripts live in `scripts/`:
+
+- `scripts/test-claude-run.sh`
+- `scripts/test-codex-run.sh`
+- `scripts/test-opencode-run.sh`

package/dist/shared/src/agent-progress.d.ts

@@ -0,0 +1,133 @@
+export type AgentProgressEventBase = {
+    sessionId?: string;
+    messageId?: string;
+    parentSessionId?: string;
+    depth?: number;
+};
+export type AgentCustomProgressEvent = AgentProgressEventBase & {
+    type: "custom";
+    pluginId: string;
+    name: string;
+    label?: string;
+    data?: Record<string, unknown>;
+};
+export type AgentModelRequestEvent = AgentProgressEventBase & {
+    type: "model_request";
+    model: string;
+    provider: string;
+    systemPrompt: string;
+    tools: Array<{
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    }>;
+    requestJson: unknown;
+};
+export type AgentDiagnosticLevel = "info" | "warn" | "error";
+export type AgentDiagnosticScope = "runner" | "session" | "plugin" | "skill" | "memory" | "tool";
+export type AgentDiagnosticEvent = AgentProgressEventBase & {
+    type: "diagnostic";
+    level: AgentDiagnosticLevel;
+    scope: AgentDiagnosticScope;
+    phase: string;
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type AgentProgressEvent = (AgentProgressEventBase & {
+    type: "start";
+    message: string;
+}) | (AgentProgressEventBase & {
+    type: "text";
+    text: string;
+}) | (AgentProgressEventBase & {
+    type: "stream_text_delta";
+    text: string;
+}) | (AgentProgressEventBase & {
+    type: "bootstrap";
+    phase: "checking" | "initializing" | "initialized" | "ready";
+    dataDir: string;
+}) | (AgentProgressEventBase & {
+    type: "session_reset";
+    action: "new" | "reset";
+    previousSessionId?: string;
+    message: string;
+}) | (AgentProgressEventBase & {
+    type: "tool_start";
+    toolCallId: string;
+    name: string;
+    input: unknown;
+}) | (AgentProgressEventBase & {
+    type: "tool_end";
+    toolCallId: string;
+    name: string;
+    input: unknown;
+    output: string;
+    isError: boolean;
+}) | (AgentProgressEventBase & {
+    type: "compaction";
+    reason: string;
+    layer?: "L1" | "L2" | "L3" | "L4" | "L5" | "L6";
+    strategy?: string;
+    estimatedTokensFreed?: number;
+    affectedEntries?: number;
+    snapshotVersion?: number;
+}) | (AgentProgressEventBase & {
+    type: "memory_changed";
+    reason: string;
+    files: string[];
+    source: "memory" | "sessions";
+    providerId?: string;
+    timestamp: string;
+}) | (AgentProgressEventBase & {
+    type: "skill_used";
+    skillName: string;
+    agent: string;
+    taskId: string;
+}) | AgentCustomProgressEvent | AgentModelRequestEvent | (AgentProgressEventBase & {
+    type: "error";
+    message: string;
+}) | (AgentProgressEventBase & {
+    type: "subagent_spawn";
+    childSessionId: string;
+    task: string;
+    label?: string;
+}) | (AgentProgressEventBase & {
+    type: "subagent_complete";
+    childSessionId: string;
+    task: string;
+    status: "done" | "error" | "killed";
+}) | (AgentProgressEventBase & {
+    type: "hitl_requested";
+    request: import("./hitl.js").HitlRequest;
+}) | (AgentProgressEventBase & {
+    type: "hitl_resumed";
+    requestId: string;
+    resolution: import("./hitl.js").HitlResolution;
+}) | (AgentProgressEventBase & {
+    type: "hitl_expired";
+    requestId: string;
+    reason: string;
+}) | (AgentProgressEventBase & {
+    type: "hitl_cancelled";
+    requestId: string;
+    reason?: string;
+}) | (AgentProgressEventBase & {
+    type: "title_updated";
+    title: string;
+}) | (AgentProgressEventBase & {
+    type: "goal_updated";
+    action: string;
+    goalId?: string;
+    goalStatus: import("./goal.js").GoalStatus | null;
+}) | (AgentProgressEventBase & {
+    type: "ui_tool_request";
+    request: import("./ui-tool.js").UiToolRequest;
+}) | (AgentProgressEventBase & {
+    type: "ui_tool_result";
+    requestId: string;
+    toolCallId: string;
+    toolName: string;
+    values: Record<string, unknown>;
+}) | AgentDiagnosticEvent;
+export declare function isAgentDiagnosticEvent(event: AgentProgressEvent): event is AgentDiagnosticEvent;
+//# sourceMappingURL=agent-progress.d.ts.map

package/dist/shared/src/agent-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-progress.d.ts","sourceRoot":"","sources":["../../../../shared/src/agent-progress.ts"],"names":[],"mappings":"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"}

package/dist/shared/src/agent-progress.js

@@ -0,0 +1,4 @@
+export function isAgentDiagnosticEvent(event) {
+    return event.type === "diagnostic";
+}
+//# sourceMappingURL=agent-progress.js.map

package/dist/shared/src/agent-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-progress.js","sourceRoot":"","sources":["../../../../shared/src/agent-progress.ts"],"names":[],"mappings":"AA8IA,MAAM,UAAU,sBAAsB,CAAC,KAAyB;IAC9D,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACrC,CAAC"}

package/dist/shared/src/context-protocol.d.ts

@@ -0,0 +1,83 @@
+export type ReadStateRecord = {
+    path: string;
+    offset?: number;
+    limit?: number;
+    contentHash: string;
+    lineCount: number;
+    capturedAt: string;
+    lastModifiedMs: number;
+};
+export type ToolResultReference = {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    storagePath: string;
+    preview: string;
+    originalChars: number;
+    truncated: boolean;
+    createdAt: string;
+};
+export type CompressionLayer = "L1" | "L2" | "L3" | "L4" | "L5" | "L6";
+export type ToolResultBudgetRecord = {
+    toolCallId: string;
+    toolName: string;
+    originalChars: number;
+    storedChars: number;
+    previewChars: number;
+    strategy: "persist";
+    createdAt: string;
+};
+export type SnipRecord = {
+    toolCallId: string;
+    toolName: string;
+    originalChars: number;
+    retainedChars: number;
+    reason: "context_dedup" | "history_snip" | "microcompact";
+    createdAt: string;
+};
+export type CollapseSpan = {
+    id: string;
+    layer: "L5";
+    startEntryIndex: number;
+    endEntryIndex: number;
+    toolNames: string[];
+    summary: string;
+    sourceCount: number;
+    estimatedTokensFreed: number;
+    createdAt: string;
+};
+export type SessionMemorySnapshot = {
+    version: 1;
+    summary: string;
+    generatedAt: string;
+    sourceEntryCount: number;
+    tokenEstimate: number;
+    trigger: "threshold" | "autocompact" | "manual";
+};
+export type ModelUsageCheckpoint = {
+    version: 1;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    coveredTranscriptEntryCount: number;
+    recordedAt: string;
+};
+export type ContextCompactionState = {
+    sessionMemory?: SessionMemorySnapshot;
+    modelUsage?: ModelUsageCheckpoint;
+    budgets: ToolResultBudgetRecord[];
+    snips: SnipRecord[];
+    collapseSpans: CollapseSpan[];
+    consecutiveAutocompactFailures: number;
+    lastCompactionAt?: string;
+    lastCompactionLayer?: CompressionLayer;
+};
+export type SessionContextSnapshot = {
+    version: 2;
+    updatedAt: string;
+    readStates: ReadStateRecord[];
+    toolResults: ToolResultReference[];
+    compaction: ContextCompactionState;
+};
+//# sourceMappingURL=context-protocol.d.ts.map

package/dist/shared/src/context-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-protocol.d.ts","sourceRoot":"","sources":["../../../../shared/src/context-protocol.ts"],"names":[],"mappings":"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"}

package/dist/shared/src/context-protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-protocol.js.map

package/dist/shared/src/context-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-protocol.js","sourceRoot":"","sources":["../../../../shared/src/context-protocol.ts"],"names":[],"mappings":""}

package/dist/shared/src/goal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Thread Goal types for @gencode/shared.
+ *
+ * Defines the cross-package contract for the lightweight thread goal system.
+ * See source/执行约束.md and artifacts/实现计划.md for design rationale.
+ */
+/** Maximum characters for inline objective in goal.json */
+export declare const MAX_GOAL_OBJECTIVE_CHARS = 4000;
+/** Maximum continuations per single runAgent call */
+export declare const MAX_GOAL_CONTINUATIONS_PER_RUN = 3;
+/**
+ * Goal status enumeration.
+ *
+ * - `active`: Being pursued; continuation turns are eligible.
+ * - `paused`: Suspended by user or system (e.g. interrupt, limit reached).
+ * - `budget_limited`: Token budget exhausted; system-steered wrap-up.
+ * - `complete`: Declared finished via model `update_goal(status=complete)`.
+ */
+export type GoalStatus = "active" | "paused" | "budget_limited" | "complete";
+/**
+ * Persisted thread goal record.
+ *
+ * Stored as `{sessionDir}/goal.json`. The `objective` field is the canonical
+ * source of truth for what the model is asked to pursue. When the objective
+ * exceeds MAX_GOAL_OBJECTIVE_CHARS, the full text is stored in an adjacent
+ * `goal-objective.md` file and `objectiveRef` points to it.
+ */
+export interface ThreadGoal {
+    /** UUID v4; replaced on each set or replace. */
+    goalId: string;
+    /** Inline objective text (≤4000 chars) or summary when objectiveRef is set. */
+    objective: string;
+    /** Relative path to `goal-objective.md` for objectives > MAX_GOAL_OBJECTIVE_CHARS. */
+    objectiveRef?: string;
+    /** Current status. */
+    status: GoalStatus;
+    /** Optional positive token budget; null means unlimited. */
+    tokenBudget: number | null;
+    /** Cumulative token consumption (non-cached input + output). */
+    tokensUsed: number;
+    /** Cumulative wall-clock seconds since goal creation (best-effort). */
+    timeUsedSeconds: number;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+    /** When true, runner injects one objective-updated steering turn then clears. */
+    pendingObjectiveUpdatedNotice?: boolean;
+}
+//# sourceMappingURL=goal.d.ts.map

package/dist/shared/src/goal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal.d.ts","sourceRoot":"","sources":["../../../../shared/src/goal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,qDAAqD;AACrD,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,CAAC;AAE7E;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC"}

package/dist/shared/src/goal.js

@@ -0,0 +1,11 @@
+/**
+ * Thread Goal types for @gencode/shared.
+ *
+ * Defines the cross-package contract for the lightweight thread goal system.
+ * See source/执行约束.md and artifacts/实现计划.md for design rationale.
+ */
+/** Maximum characters for inline objective in goal.json */
+export const MAX_GOAL_OBJECTIVE_CHARS = 4000;
+/** Maximum continuations per single runAgent call */
+export const MAX_GOAL_CONTINUATIONS_PER_RUN = 3;
+//# sourceMappingURL=goal.js.map

package/dist/shared/src/goal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal.js","sourceRoot":"","sources":["../../../../shared/src/goal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C,qDAAqD;AACrD,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC"}

package/dist/shared/src/hitl.d.ts

@@ -0,0 +1,214 @@
+/**
+ * HITL (Human-In-The-Loop) protocol types for AIMax.
+ *
+ * These types define the stable public contract shared by all packages:
+ *   - @gencode/agents (produces pause requests)
+ *   - @gencode/cli    (emits & receives HITL events)
+ *   - @gencode/web    (renders HITL UI)
+ *   - external systems (爱码 Max)
+ *
+ * Design principles:
+ *   1. Pause is a persisted session state, not an in-process block.
+ *   2. Resume is explicit & structured, not implicit message concatenation.
+ *   3. Every request carries an idempotency-safe requestId.
+ *   4. A single HitlRequest model covers approval / clarify / review.
+ */
+/** The semantic category of a HITL interaction. */
+export type HitlKind = "approval" | "clarify" | "review";
+/** A single selectable choice presented to the user. */
+export type HitlChoice = {
+    id: string;
+    label: string;
+    description?: string;
+};
+/** Choice-based input (radio / checkbox / select). */
+export type HitlChoiceInput = {
+    mode: "choice";
+    /** Allow selecting more than one choice. */
+    multiple?: boolean;
+    choices: HitlChoice[];
+    /** If true the user may also provide free-form text alongside choices. */
+    allowFreeText?: boolean;
+};
+/** Free-text input (single or multi-line). */
+export type HitlTextInput = {
+    mode: "text";
+    multiline?: boolean;
+    placeholder?: string;
+};
+/** Structured form input backed by a JSON-schema-like descriptor. */
+export type HitlFormInput = {
+    mode: "form";
+    /** JSON-Schema-like descriptor understood by the rendering layer. */
+    schema: Record<string, unknown>;
+};
+/** Union of all supported input modes. */
+export type HitlInputSchema = HitlChoiceInput | HitlTextInput | HitlFormInput;
+/** Rich preview attachment that accompanies a review request. */
+export type HitlPreview = {
+    mimeType: "text/plain" | "application/json" | "text/markdown";
+    content: string;
+};
+/** Timeout / default-action policy attached to a request. */
+export type HitlPolicy = {
+    /** How long the external system should wait (ms) before timing out. */
+    timeoutMs?: number;
+    /** What to do when the request times out without a human response. */
+    defaultOnTimeout?: "deny" | "cancel" | "continue" | "use_best_effort";
+    /** Always true — this request can be resumed later. */
+    resumable: true;
+};
+/**
+ * A HITL pause request produced by `@gencode/agents` and emitted through
+ * `@gencode/cli` to external systems.
+ */
+export type HitlRequest = {
+    /** Globally-unique request identifier (UUID). */
+    requestId: string;
+    /** The session this request belongs to. */
+    sessionId: string;
+    /** Optional correlation message id. */
+    messageId?: string;
+    /** Semantic kind of HITL interaction. */
+    kind: HitlKind;
+    /** Short human-readable title for the pause card. */
+    title: string;
+    /** Longer prompt / description explaining what the agent needs. */
+    prompt: string;
+    /** Arbitrary structured details for the rendering layer. */
+    details?: Record<string, unknown>;
+    /** Optional rich preview (e.g. draft document). */
+    preview?: HitlPreview;
+    /** Describes the expected user input shape. */
+    input: HitlInputSchema;
+    /** Timeout & default-action policy. */
+    policy: HitlPolicy;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 expiration timestamp (optional). */
+    expiresAt?: string;
+};
+/** The structured user response that resolves a HITL request. */
+export type HitlResolution = {
+    /** Must match the original `HitlRequest.requestId`. */
+    requestId: string;
+    /** Must match the original session. */
+    sessionId: string;
+    /** Resolution action. */
+    action: "submit" | "cancel" | "timeout";
+    /** User-provided values (present when action === "submit"). */
+    values?: {
+        selectedChoiceIds?: string[];
+        text?: string;
+        form?: Record<string, unknown>;
+    };
+    /** Who submitted the resolution. */
+    submittedBy?: {
+        userId?: string;
+        channel?: string;
+    };
+    /** Caller-supplied idempotency key to prevent duplicate processing. */
+    idempotencyKey?: string;
+    /** ISO-8601 submission timestamp. */
+    submittedAt: string;
+};
+/** The checkpoint phase at which the agent was paused. */
+export type HitlCheckpointPhase = "before_tool" | "after_tool" | "before_finalize" | "custom";
+/** Describes the execution checkpoint so the agent can resume. */
+export type HitlCheckpoint = {
+    /** Turn identifier for resume tracking. */
+    turnId: string;
+    /** The phase within the turn where the pause occurred. */
+    phase: HitlCheckpointPhase;
+    /** Strategy used to resume from this checkpoint. */
+    resumeStrategy: "reenter_from_checkpoint";
+};
+/** Tool call metadata used for precise resume of pre-tool pauses. */
+export type HitlToolContext = {
+    toolCallId: string;
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+};
+/** Status of a pending HITL request within a session. */
+export type HitlStatus = "pending" | "resolved" | "expired" | "cancelled";
+/** Persisted state written to `pending-hitl.json` in the session directory. */
+export type PausedRunState = {
+    /** Schema version for forward-compatibility. */
+    version: 1;
+    /** Session identifier. */
+    sessionId: string;
+    /** The HITL request that caused the pause. */
+    request: HitlRequest;
+    /** Current status of the HITL request. */
+    status: HitlStatus;
+    /** Execution checkpoint for resume. */
+    checkpoint: HitlCheckpoint;
+    /** Contextual metadata. */
+    context: {
+        agentId?: string;
+        channel?: string;
+        parentSessionId?: string;
+        depth?: number;
+    };
+    /** Present when the pause happened immediately before a tool execution. */
+    toolContext?: HitlToolContext;
+    /** Present once the request has been resolved. */
+    resolution?: HitlResolution;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    updatedAt: string;
+};
+/** A single entry in the append-only `hitl-history.jsonl` audit log. */
+export type HitlHistoryEntry = {
+    /** The request ID this entry relates to. */
+    requestId: string;
+    sessionId: string;
+    /** The action recorded by this entry. */
+    action: "requested" | "resolved" | "expired" | "cancelled";
+    /** Snapshot of the request (on "requested") or resolution (on "resolved"). */
+    payload: HitlRequest | HitlResolution;
+    /** ISO-8601 timestamp of this log entry. */
+    timestamp: string;
+};
+/**
+ * The canonical set of tool names that are dedicated HITL interaction tools.
+ * Tools in this set are expected to produce transcript entries (assistant tool
+ * call + tool result) that form the human-interaction record. Tools NOT in
+ * this set (e.g. "exec", "apply_patch") may throw `HitlPauseSignal` for
+ * safety approvals, but their pauses should be transparent — no HITL artefacts
+ * should appear in the transcript.
+ */
+export declare const HITL_TOOL_NAMES: ReadonlySet<string>;
+/** Returns true when the tool name is a dedicated HITL interaction tool. */
+export declare function isHitlTool(toolName: string): boolean;
+/** Type-guard: check whether a PausedRunState is still actionable. */
+export declare function isHitlPending(state: PausedRunState): boolean;
+/** Type-guard: check whether a PausedRunState has been resolved. */
+export declare function isHitlResolved(state: PausedRunState): boolean;
+/** Check whether a HITL request has expired based on its `expiresAt` field. */
+export declare function isHitlExpired(request: HitlRequest, now?: Date): boolean;
+/**
+ * Parses plain text only when it exactly matches a HITL UI action.
+ *
+ * This is intentionally stricter than `parseTextToResolution`: it never falls
+ * back to free text. It is used by generic message entry points to decide
+ * whether a normal user message should resolve a pending HITL request or start
+ * a new task.
+ */
+export declare function parseMatchedTextToResolution(text: string, request: HitlRequest): HitlResolution | null;
+/**
+ * Parses a plain-text user response into a structured `HitlResolution`.
+ *
+ * This is designed for IM channels (快乐平安 IM, etc.) that cannot render
+ * rich UI components. The user simply replies with text like "同意", "拒绝",
+ * or free-form feedback.
+ *
+ * Matching logic:
+ *   1. If the text matches a choice label or known synonym → `action: "submit"` with that choice.
+ *   2. If the request accepts free text and no choice matched → `action: "submit"` with text value.
+ *   3. If the text looks like a cancellation keyword → `action: "cancel"`.
+ *   4. Otherwise → `action: "submit"` with text value (fallback to free text).
+ */
+export declare function parseTextToResolution(text: string, request: HitlRequest): HitlResolution;
+//# sourceMappingURL=hitl.d.ts.map

package/dist/shared/src/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","sourceRoot":"","sources":["../../../../shared/src/hitl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,mDAAmD;AACnD,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAIzD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,aAAa,GAAG,aAAa,CAAC;AAI9E,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,YAAY,GAAG,kBAAkB,GAAG,eAAe,CAAC;IAC9D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG;IACvB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,iBAAiB,CAAC;IACtE,uDAAuD;IACvD,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,mDAAmD;IACnD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,+CAA+C;IAC/C,KAAK,EAAE,eAAe,CAAC;IACvB,uCAAuC;IACvC,MAAM,EAAE,UAAU,CAAC;IACnB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG;IAC3B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACxC,+DAA+D;IAC/D,MAAM,CAAC,EAAE;QACP,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,CAAC;IACF,oCAAoC;IACpC,WAAW,CAAC,EAAE;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAIF,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,QAAQ,CAAC;AAEb,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG;IAC3B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,mBAAmB,CAAC;IAC3B,oDAAoD;IACpD,cAAc,EAAE,yBAAyB,CAAC;CAC3C,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAE1E,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,OAAO,EAAE,CAAC,CAAC;IACX,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,WAAW,CAAC;IACrB,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,cAAc,CAAC;IAC3B,2BAA2B;IAC3B,OAAO,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,2EAA2E;IAC3E,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kDAAkD;IAClD,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAIF,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IAC3D,8EAA8E;IAC9E,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC;IACtC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE7D;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAGnF;AAwED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,GACnB,cAAc,GAAG,IAAI,CA0BvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,GACnB,cAAc,CAiDhB"}