@claudexor/schema 1.0.0

package/dist/telemetry.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { AccessProfile, ExternalContextPolicy, Id, IsoTimestamp, ModeKind, SchemaVersion, } from "./primitives.js";
+import { ToolKind } from "./harness.js";
+/**
+ * Run telemetry artifact (`final/telemetry.yaml`).
+ *
+ * The orchestrator is the ONLY computer of web/tool evidence. Surfaces
+ * (control-api, CLI, app) project this artifact; they must not re-derive
+ * evidence from raw events. Legacy runs without the artifact render an honest
+ * "telemetry unavailable" state instead of a recomputed guess.
+ */
+export const WebEvidenceStatus = z
+    .enum(["none", "attempted", "satisfied", "failed", "unverified"])
+    .describe("Web-evidence verdict for an attempt/run: none (no web activity), attempted, satisfied (required evidence produced), failed, or unverified.");
+export const WebEvidenceRecord = z
+    .object({
+    required: z.boolean().default(false).describe("Whether the run required web evidence."),
+    /** Requested policy for the run. */
+    policy: ExternalContextPolicy.default("auto").describe("Requested web policy for the run."),
+    /** Mode actually executed by the harness route (e.g. claude `cached` upgrades to `live`, disclosed). */
+    effective_mode: ExternalContextPolicy.default("auto").describe("Policy actually executed by the harness route (disclosed upgrades, e.g. cached to live)."),
+    attempted: z.boolean().default(false).describe("Whether any web activity was attempted."),
+    satisfied: z.boolean().default(false).describe("Whether the web-evidence requirement was satisfied."),
+    status: WebEvidenceStatus.default("none"),
+    tool: z.string().nullable().default(null).describe("Web tool that produced the evidence, when any."),
+    target: z.string().nullable().default(null).describe("Redacted target (query/url) of the web activity, when any."),
+    error_summary: z.string().nullable().default(null).describe("Redacted error detail when web activity failed."),
+})
+    .describe("Typed web-evidence record computed by the orchestrator; surfaces project it and never re-derive evidence from raw events.");
+export const ToolErrorRecord = z
+    .object({
+    tool: z.string().describe("Native tool name that errored."),
+    kind: ToolKind.default("other"),
+    target: z.string().nullable().default(null).describe("Redacted target of the tool use, when known."),
+    summary: z.string().describe("Redacted error summary."),
+    /** True when a later successful result of the same tool exists in the same attempt. */
+    recovered: z.boolean().default(false).describe("True when a later successful result of the same tool exists in the same attempt."),
+    tool_use_id: z.string().nullable().default(null).describe("Tool use id correlating the error to its call, when known."),
+})
+    .describe("One tool error observed during an attempt.");
+export const TransientFailureRecord = z
+    .object({
+    kind: z
+        .enum(["network", "stream_disconnect", "service_unavailable", "timeout", "unknown"])
+        .default("unknown")
+        .describe("Kind of transient failure."),
+    retry_delay_ms: z.number().int().nonnegative().nullable().default(null).describe("Suggested retry delay in milliseconds, when reported."),
+})
+    .describe("An adapter-declared transient failure that informed bounded retry policy.");
+export const AttemptOutcomeStatus = z
+    .enum(["success", "success_with_warnings", "blocked", "failed"])
+    .describe("Outcome of one attempt: success, success_with_warnings, blocked, or failed.");
+/**
+ * Contract/outcome truth for one attempt. Tool errors are tracked separately
+ * from whether the attempt produced the work product the intent asked for.
+ */
+export const AttemptOutcome = z
+    .object({
+    deliverable_present: z.boolean().default(false).describe("Whether the attempt produced the deliverable the intent asked for."),
+    gates_passed: z.boolean().nullable().default(null).describe("Whether deterministic gates passed; null when no gates ran."),
+    harness_errored: z.boolean().default(false).describe("Whether the harness itself errored."),
+    web_required_unsatisfied: z.boolean().default(false).describe("True when required web evidence was not satisfied."),
+    tool_warnings_count: z.number().int().nonnegative().default(0).describe("Count of tool warnings in the attempt."),
+    status: AttemptOutcomeStatus.default("success"),
+})
+    .describe("Contract/outcome truth for one attempt; tool errors are tracked separately from deliverable production.");
+export const AttemptTelemetryRecord = z
+    .object({
+    attempt_id: Id.describe("Attempt id."),
+    harness_id: Id.describe("Harness that ran the attempt."),
+    /**
+     * Model identity the harness stream actually reported (route evidence).
+     * Null when the stream never disclosed one; surfaces must render that as
+     * unverified, never as a guess.
+     */
+    observed_model: z
+        .string()
+        .nullable()
+        .default(null)
+        .describe("Model the harness stream actually reported; null when never disclosed (rendered as unverified, never guessed)."),
+    web: WebEvidenceRecord,
+    /** Bounded by the writer (most recent first when truncated; `tool_errors_total` keeps the true count). */
+    tool_errors: z
+        .array(ToolErrorRecord)
+        .default([])
+        .describe("Tool errors, bounded by the writer (most recent first when truncated; tool_errors_total keeps the true count)."),
+    tool_errors_total: z.number().int().nonnegative().default(0).describe("True total count of tool errors."),
+    unrecovered_tool_errors: z.number().int().nonnegative().default(0).describe("Tool errors with no later successful recovery."),
+    /** tool_result events that arrived WITHOUT a status field (never treated as ok). */
+    statusless_tool_results: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("tool_result events that arrived without a status field (never treated as ok)."),
+    /** Native lines/events the adapter could not parse or did not recognize (never silently zero). */
+    dropped_events: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Native lines/events the adapter could not parse or did not recognize (never silently zero)."),
+    /** Adapter-declared transient failures that informed bounded retry policy. */
+    transient_failures: z
+        .array(TransientFailureRecord)
+        .default([])
+        .describe("Adapter-declared transient failures that informed bounded retry policy."),
+    /** Contract/outcome projection for this attempt. */
+    outcome: AttemptOutcome.default({}),
+})
+    .describe("Telemetry for one attempt: route evidence, web evidence, tool errors, dropped events, and outcome.");
+export const RunTelemetry = z
+    .object({
+    schema_version: SchemaVersion,
+    run_id: Id.describe("Run the telemetry belongs to."),
+    task_id: Id.describe("Task the run belongs to."),
+    mode: ModeKind,
+    requested_access: AccessProfile.describe("Access profile the caller requested."),
+    effective_access: AccessProfile.describe("Access profile actually enforced by the engine."),
+    external_context_policy: ExternalContextPolicy.describe("Requested web policy for the run."),
+    effective_web_mode: ExternalContextPolicy.describe("Web policy actually executed by the selected route."),
+    web_required: z.boolean().default(false).describe("Whether the run required web evidence."),
+    /** Attempt whose output became the final answer/patch; null when no attempt succeeded. */
+    final_attempt_id: Id.nullable()
+        .default(null)
+        .describe("Attempt whose output became the final answer/patch; null when no attempt succeeded."),
+    /** Run-level web evidence: the final attempt's evidence, else the most severe attempt evidence. */
+    web: WebEvidenceRecord.describe("Run-level web evidence: the final attempt's evidence, else the most severe attempt evidence."),
+    attempts: z.array(AttemptTelemetryRecord).default([]).describe("Per-attempt telemetry records."),
+    /** Sum of attempt outcome warnings; surfaces render this separately from terminal state. */
+    tool_warnings_total: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe("Sum of attempt tool warnings; rendered separately from terminal state."),
+    generated_at: IsoTimestamp.describe("When the telemetry artifact was generated."),
+})
+    .describe("Run telemetry artifact (final/telemetry.yaml), the single computed source of web/tool evidence; surfaces project it and never re-derive evidence from raw events.");
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

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

package/dist/thread.d.ts

@@ -0,0 +1,348 @@
+import { z } from "zod";
+/**
+ * Threads / Sessions are the v0.9 chat/session-first SSOT.
+ *
+ * A `Thread` is a Claudexor-owned conversation about a project; runs are "turns"
+ * (moves) inside it. A `Session` is the *vendor* CLI session bound to one harness
+ * for one thread — a re-hostable CACHE, not the source of truth. When a turn
+ * cannot resume the native session in place (isolated-envelope candidates,
+ * race lanes included, or re-hosting onto a different harness) the engine
+ * serializes a `SessionReboundLineage` and emits a typed `session.rebound`
+ * event (honest, lossy disclosure — never silent).
+ */
+/** A thread is open or explicitly closed (archived). "Blocked" is not a thread
+ * state — it is a live projection of whether the head turn's run needs a human. */
+export declare const ThreadState: z.ZodEnum<["active", "closed"]>;
+export type ThreadState = z.infer<typeof ThreadState>;
+export declare const SessionState: z.ZodEnum<["live", "stale", "rebound"]>;
+export type SessionState = z.infer<typeof SessionState>;
+/** How a session can be continued on its native CLI. Staged-field rule:
+ * only values the daemon actually stamps (`resume_by_id` when a native
+ * session id exists, `none` otherwise). */
+export declare const SessionResumeKind: z.ZodEnum<["resume_by_id", "none"]>;
+export type SessionResumeKind = z.infer<typeof SessionResumeKind>;
+export declare const ThreadTurnKind: z.ZodEnum<["initial", "followup", "decision"]>;
+export type ThreadTurnKind = z.infer<typeof ThreadTurnKind>;
+/**
+ * Per-thread workspace mode (v0.10). `in_place` mutates the live project tree
+ * directly (continuity is the tree itself; native vendor sessions resume); the
+ * default, matching how Claude Code / Cursor work locally. `isolated` keeps a
+ * persistent git worktree per thread; turns accumulate there and `apply` merges
+ * into the project. Race candidates always run in throwaway envelopes regardless.
+ */
+export declare const WorkspaceMode: z.ZodEnum<["in_place", "isolated"]>;
+export type WorkspaceMode = z.infer<typeof WorkspaceMode>;
+export declare const ThreadWorkspace: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<["in_place", "isolated"]>>;
+    /** Set lazily on the first write turn of an isolated thread. */
+    worktree_path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Snapshot SHA the isolated worktree (or last apply) is based on. */
+    base_sha: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    mode: "in_place" | "isolated";
+    worktree_path: string | null;
+    base_sha: string | null;
+}, {
+    mode?: "in_place" | "isolated" | undefined;
+    worktree_path?: string | null | undefined;
+    base_sha?: string | null | undefined;
+}>;
+export type ThreadWorkspace = z.infer<typeof ThreadWorkspace>;
+/** The Claudexor-owned conversation. SSOT for lineage; vendor sessions are caches. */
+export declare const Thread: z.ZodObject<{
+    schema_version: z.ZodLiteral<2>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    /** Project the thread is anchored to; null for a no-project Ask thread. */
+    repo: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        root: z.ZodString;
+        base_ref: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        root: string;
+        base_ref: string;
+    }, {
+        root: string;
+        base_ref: string;
+    }>>>;
+    title: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Default mode for new turns; individual turns may override. */
+    mode: z.ZodDefault<z.ZodEnum<["ask", "plan", "audit", "agent", "orchestrate"]>>;
+    /** Per-thread auth preference override (subscription/api_key/auto). */
+    auth_preference: z.ZodDefault<z.ZodEnum<["subscription", "api_key", "auto"]>>;
+    /** Sticky orchestrate/primary harness for the thread (re-routable). A bias /
+     * ordering hint, NOT a privileged role — orderPool just pins it first. */
+    primary_harness: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Sticky eligible harness pool for the thread (Best-of runs this pool, one
+     * candidate per harness). Empty => the engine auto-pools doctor-ok harnesses.
+     * primary_harness, when set, must be a member of this pool when non-empty. */
+    eligible_harnesses: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** How turns touch files (in-place live tree vs isolated worktree). */
+    workspace: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["in_place", "isolated"]>>;
+        /** Set lazily on the first write turn of an isolated thread. */
+        worktree_path: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** Snapshot SHA the isolated worktree (or last apply) is based on. */
+        base_sha: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "in_place" | "isolated";
+        worktree_path: string | null;
+        base_sha: string | null;
+    }, {
+        mode?: "in_place" | "isolated" | undefined;
+        worktree_path?: string | null | undefined;
+        base_sha?: string | null | undefined;
+    }>>;
+    /** Ordered run lineage (each run is a turn move). */
+    run_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    head_run_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    state: z.ZodDefault<z.ZodEnum<["active", "closed"]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    auth_preference: "auto" | "subscription" | "api_key";
+    title: string | null;
+    mode: "ask" | "plan" | "audit" | "agent" | "orchestrate";
+    schema_version: 2;
+    created_at: string;
+    updated_at: string;
+    repo: {
+        root: string;
+        base_ref: string;
+    } | null;
+    primary_harness: string | null;
+    eligible_harnesses: string[];
+    workspace: {
+        mode: "in_place" | "isolated";
+        worktree_path: string | null;
+        base_sha: string | null;
+    };
+    run_ids: string[];
+    head_run_id: string | null;
+    state: "active" | "closed";
+}, {
+    id: string;
+    schema_version: 2;
+    created_at: string;
+    updated_at: string;
+    auth_preference?: "auto" | "subscription" | "api_key" | undefined;
+    title?: string | null | undefined;
+    mode?: "ask" | "plan" | "audit" | "agent" | "orchestrate" | undefined;
+    repo?: {
+        root: string;
+        base_ref: string;
+    } | null | undefined;
+    primary_harness?: string | null | undefined;
+    eligible_harnesses?: string[] | undefined;
+    workspace?: {
+        mode?: "in_place" | "isolated" | undefined;
+        worktree_path?: string | null | undefined;
+        base_sha?: string | null | undefined;
+    } | undefined;
+    run_ids?: string[] | undefined;
+    head_run_id?: string | null | undefined;
+    state?: "active" | "closed" | undefined;
+}>;
+export type Thread = z.infer<typeof Thread>;
+/** A re-hostable pointer to one harness's native CLI session for a thread. */
+export declare const Session: z.ZodObject<{
+    id: z.ZodString;
+    thread_id: z.ZodString;
+    harness_id: z.ZodString;
+    /** The vendor CLI session id (codex thread id / claude session uuid / ...). */
+    native_session_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resume_kind: z.ZodDefault<z.ZodEnum<["resume_by_id", "none"]>>;
+    last_observed_model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    state: z.ZodDefault<z.ZodEnum<["live", "stale", "rebound"]>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    harness_id: string;
+    created_at: string;
+    updated_at: string;
+    state: "live" | "stale" | "rebound";
+    thread_id: string;
+    native_session_id: string | null;
+    resume_kind: "none" | "resume_by_id";
+    last_observed_model: string | null;
+}, {
+    id: string;
+    harness_id: string;
+    created_at: string;
+    updated_at: string;
+    thread_id: string;
+    state?: "live" | "stale" | "rebound" | undefined;
+    native_session_id?: string | null | undefined;
+    resume_kind?: "none" | "resume_by_id" | undefined;
+    last_observed_model?: string | null | undefined;
+}>;
+export type Session = z.infer<typeof Session>;
+/**
+ * Well-known machine code for the trust-gate refusal (access=full without the
+ * user-level allow). ONE producer — the engine's trust gate throw — and typed
+ * consumers (the macOS one-click remedy keys on it; never substring matching
+ * on the human message). New gates may attach their own codes without a
+ * schema change: `code` is an open string by design.
+ */
+export declare const TRUST_FULL_ACCESS_CODE = "trust_full_access_required";
+/**
+ * Typed record of a turn whose run could not be enqueued/started (e.g. the
+ * trust gate refused `access: full`). Persisted ON the turn so every surface
+ * renders the honest refusal inline — a runless turn must never be a silent
+ * orphan whose reason lived only in one HTTP response (INV-093). Cleared when
+ * a retry binds a run.
+ */
+export declare const TurnEnqueueError: z.ZodObject<{
+    message: z.ZodString;
+    /** Machine-readable refusal code carried from the throwing gate (e.g.
+     * TRUST_FULL_ACCESS_CODE); null when the failure had no typed code. */
+    code: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Whether retry can REPLAY this turn: true when a job was recorded before
+     * the failure (the registry holds the params to replay); false when the
+     * enqueue itself threw and no job exists — surfaces then offer "send a new
+     * message" instead of a doomed Retry. */
+    retryable: z.ZodDefault<z.ZodBoolean>;
+    failed_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string | null;
+    message: string;
+    retryable: boolean;
+    failed_at: string;
+}, {
+    message: string;
+    failed_at: string;
+    code?: string | null | undefined;
+    retryable?: boolean | undefined;
+}>;
+export type TurnEnqueueError = z.infer<typeof TurnEnqueueError>;
+/** One follow-up unit within a thread (a run is its backing execution). */
+export declare const ThreadTurn: z.ZodObject<{
+    id: z.ZodString;
+    thread_id: z.ZodString;
+    run_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    parent_run_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Set when this turn implements an approved plan from an earlier plan run. */
+    plan_run_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodDefault<z.ZodEnum<["initial", "followup", "decision"]>>;
+    prompt: z.ZodDefault<z.ZodString>;
+    /** Files/images the user attached to this turn (resolved scoped paths). */
+    attachments: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodDefault<z.ZodEnum<["image", "file"]>>;
+        mime: z.ZodDefault<z.ZodString>;
+        name: z.ZodDefault<z.ZodString>;
+        path: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        id: string;
+        kind: "image" | "file";
+        mime: string;
+        name: string;
+    }, {
+        path: string;
+        id: string;
+        kind?: "image" | "file" | undefined;
+        mime?: string | undefined;
+        name?: string | undefined;
+    }>, "many">>;
+    /** Why this turn has no run (enqueue/preflight refusal); null once a run binds. */
+    enqueue_error: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        message: z.ZodString;
+        /** Machine-readable refusal code carried from the throwing gate (e.g.
+         * TRUST_FULL_ACCESS_CODE); null when the failure had no typed code. */
+        code: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        /** Whether retry can REPLAY this turn: true when a job was recorded before
+         * the failure (the registry holds the params to replay); false when the
+         * enqueue itself threw and no job exists — surfaces then offer "send a new
+         * message" instead of a doomed Retry. */
+        retryable: z.ZodDefault<z.ZodBoolean>;
+        failed_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        code: string | null;
+        message: string;
+        retryable: boolean;
+        failed_at: string;
+    }, {
+        message: string;
+        failed_at: string;
+        code?: string | null | undefined;
+        retryable?: boolean | undefined;
+    }>>>;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: "initial" | "followup" | "decision";
+    prompt: string;
+    attachments: {
+        path: string;
+        id: string;
+        kind: "image" | "file";
+        mime: string;
+        name: string;
+    }[];
+    created_at: string;
+    thread_id: string;
+    run_id: string | null;
+    parent_run_id: string | null;
+    plan_run_id: string | null;
+    enqueue_error: {
+        code: string | null;
+        message: string;
+        retryable: boolean;
+        failed_at: string;
+    } | null;
+}, {
+    id: string;
+    created_at: string;
+    thread_id: string;
+    kind?: "initial" | "followup" | "decision" | undefined;
+    prompt?: string | undefined;
+    attachments?: {
+        path: string;
+        id: string;
+        kind?: "image" | "file" | undefined;
+        mime?: string | undefined;
+        name?: string | undefined;
+    }[] | undefined;
+    run_id?: string | null | undefined;
+    parent_run_id?: string | null | undefined;
+    plan_run_id?: string | null | undefined;
+    enqueue_error?: {
+        message: string;
+        failed_at: string;
+        code?: string | null | undefined;
+        retryable?: boolean | undefined;
+    } | null | undefined;
+}>;
+export type ThreadTurn = z.infer<typeof ThreadTurn>;
+/**
+ * The lossy payload serialized when a turn cannot resume the native session
+ * in place: isolated-envelope candidates (race lanes included) and re-hosting
+ * onto a different harness (no native memory of the old session). Carried by
+ * the typed `session.rebound` event; the disclosure is explicit, never silent.
+ */
+export declare const SessionReboundLineage: z.ZodObject<{
+    thread_id: z.ZodString;
+    harness_id: z.ZodString;
+    /** The vendor native session id we are leaving behind (not a Claudexor Id). */
+    from_native_session_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    to_session_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    summary: z.ZodDefault<z.ZodString>;
+    reason: z.ZodDefault<z.ZodEnum<["quota_exhausted", "money_exhausted", "subscription_exhausted", "rate_limited", "harness_error", "stall", "web_evidence_unsatisfied", "fallback_model", "not_portable", "auth_unavailable", "readiness_preferred", "manual"]>>;
+}, "strip", z.ZodTypeAny, {
+    harness_id: string;
+    thread_id: string;
+    from_native_session_id: string | null;
+    to_session_id: string | null;
+    summary: string;
+    reason: "quota_exhausted" | "money_exhausted" | "subscription_exhausted" | "rate_limited" | "harness_error" | "stall" | "web_evidence_unsatisfied" | "fallback_model" | "not_portable" | "auth_unavailable" | "readiness_preferred" | "manual";
+}, {
+    harness_id: string;
+    thread_id: string;
+    from_native_session_id?: string | null | undefined;
+    to_session_id?: string | null | undefined;
+    summary?: string | undefined;
+    reason?: "quota_exhausted" | "money_exhausted" | "subscription_exhausted" | "rate_limited" | "harness_error" | "stall" | "web_evidence_unsatisfied" | "fallback_model" | "not_portable" | "auth_unavailable" | "readiness_preferred" | "manual" | undefined;
+}>;
+export type SessionReboundLineage = z.infer<typeof SessionReboundLineage>;
+//# sourceMappingURL=thread.d.ts.map

package/dist/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../src/thread.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;;;;;;;GAUG;AAEH;mFACmF;AACnF,eAAO,MAAM,WAAW,iCAEwG,CAAC;AACjI,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,YAAY,yCAE4E,CAAC;AACtG,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;2CAE2C;AAC3C,eAAO,MAAM,iBAAiB,qCAEkG,CAAC;AACjI,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,eAAO,MAAM,cAAc,gDAEuE,CAAC;AACnG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,qCAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;IAGxB,gEAAgE;;IAMhE,sEAAsE;;;;;;;;;;EAGkB,CAAC;AAC7F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,sFAAsF;AACtF,eAAO,MAAM,MAAM;;;;;IAMf,2EAA2E;;;;;;;;;;;;IAU3E,iEAAiE;;IAEjE,uEAAuE;;IAEvE;8EAC0E;;IAM1E;;kFAE8E;;IAO9E,uEAAuE;;;QAjDvE,gEAAgE;;QAMhE,sEAAsE;;;;;;;;;;;IA6CtE,qDAAqD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK+E,CAAC;AACzI,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,OAAO;;;;IAKhB,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYsC,CAAC;AAC1H,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,OAAO,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;IAGzB;2EACuE;;IAMvE;;;6CAGyC;;;;;;;;;;;;;EAS1C,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,2EAA2E;AAC3E,eAAO,MAAM,UAAU;;;;;IAMnB,+EAA+E;;;;IAI/E,2EAA2E;;;;;;;;;;;;;;;;;;;;IAE3E,mFAAmF;;;QAnCnF;+EACuE;;QAMvE;;;iDAGyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BqC,CAAC;AACnF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;IAI9B,+EAA+E;;;;;;;;;;;;;;;;;;;EAYhF,CAAC;AACJ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}