@yaklabs-ai/plugin-sdk 0.13.10 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/kay-app.d.ts CHANGED
@@ -692,7 +692,7 @@ export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
692
692
  declare function Create(hidden: ObjectLike_2, enumerable: ObjectLike_2, options?: ObjectLike_2): ObjectLike_2;
693
693
 
694
694
  /**
695
- * The `signals` a host with no Jev lane or no signals store binds: `observe` never touches the
695
+ * The `signals` a host with no System One or no signals store binds: `observe` never touches the
696
696
  * network, answers `invalid` for an input that breaks the recorded-name grammar exactly as a
697
697
  * real host would, and otherwise `unavailable` with `stored: false`; both reads answer
698
698
  * `unavailable` with reason `no-store`. So a caller's result handling does not change with host
@@ -700,17 +700,6 @@ declare function Create(hidden: ObjectLike_2, enumerable: ObjectLike_2, options?
700
700
  */
701
701
  export declare function createFallbackOnlySignals(): KayAppSignals;
702
702
 
703
- /**
704
- * The `withJev` a host with no Jev lane binds: `use` is never called, no client is ever built,
705
- * and no network is ever touched. It keeps the cancellation contract identical to the real
706
- * wrapper's so a caller's `signal`/`deadlineAt` handling does not change with host composition.
707
- *
708
- * Deliberately here rather than in the runtime: this is the DEFAULT for the SDK's own host
709
- * factory, which cannot import the runtime uphill. The runtime also delegates fallback execution
710
- * here, so both paths share cancellation, deadline enforcement, and cleanup.
711
- */
712
- export declare function createFallbackOnlyWithJev(): WithJev;
713
-
714
703
  /**
715
704
  * The `app.skills` a host with no skill store or catalog binds: every read answers
716
705
  * `not-available`, so a plugin's code path never depends on host composition.
@@ -816,6 +805,8 @@ declare type DaemonServiceTurnMessage = CustomMessage<DaemonServiceTurnDetails>
816
805
  readonly display: true;
817
806
  };
818
807
 
808
+ declare type DecideAnswer = DecideBoolAnswer | DecideChoiceAnswer | DecideScoreAnswer;
809
+
819
810
  declare type DecideAnswerFor<Q> = Q extends DecideBoolQuestion ? DecideBoolAnswer : Q extends DecideChoiceQuestion<infer L> ? DecideChoiceAnswer<L> : Q extends DecideScoreQuestion ? DecideScoreAnswer : never;
820
811
 
821
812
  declare interface DecideBoolAnswer {
@@ -1795,150 +1786,6 @@ declare function IsUnsafe(value: unknown): value is TUnsafe;
1795
1786
  /** Returns true if the given value is TVoid. */
1796
1787
  declare function IsVoid(value: unknown): value is TVoid;
1797
1788
 
1798
- export declare type JevAnswer = JevBoolAnswer | JevChoiceAnswer | JevScoreAnswer;
1799
-
1800
- /** The answer shape one question gets back. */
1801
- export declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
1802
-
1803
- export declare interface JevBoolAnswer {
1804
- readonly type: "bool";
1805
- /** P(yes), from 0 to 1. */
1806
- readonly probability: number;
1807
- }
1808
-
1809
- /** A yes/no question. `criteria` says what yes and what no mean; omit it to leave both open. */
1810
- export declare interface JevBoolQuestion {
1811
- readonly type: "bool";
1812
- readonly instructions: string;
1813
- readonly criteria?: {
1814
- readonly true: string;
1815
- readonly false: string;
1816
- };
1817
- }
1818
-
1819
- /**
1820
- * The one error `classify` rejects with. It carries a classification, never the provider's own
1821
- * message or body: those can echo the request state, and this error reaches logs.
1822
- */
1823
- export declare class JevCallError extends Error {
1824
- readonly transport: JevTransport;
1825
- readonly kind: JevCallErrorKind;
1826
- /** The final attempt's HTTP status, when a response arrived. */
1827
- readonly status: number | undefined;
1828
- constructor(init: {
1829
- readonly transport: JevTransport;
1830
- readonly kind: JevCallErrorKind;
1831
- readonly status?: number | undefined;
1832
- });
1833
- }
1834
-
1835
- /**
1836
- * Why a Jev call failed, as a closed set:
1837
- *
1838
- * - `http`: the route answered with an error status (`status` says which).
1839
- * - `too-large`: the route refused the request's size (413, or a 400 naming the token limit).
1840
- * - `network`: no response arrived.
1841
- * - `aborted`: the call was cancelled.
1842
- * - `invalid-answer`: the route answered, but not with an answer for every asked question.
1843
- */
1844
- export declare type JevCallErrorKind = "http" | "too-large" | "network" | "aborted" | "invalid-answer";
1845
-
1846
- export declare interface JevChoiceAnswer<L extends string = string> {
1847
- readonly type: "choice";
1848
- readonly choice: L;
1849
- readonly confidence: number;
1850
- /** P(label) for every offered label. */
1851
- readonly probabilities: Readonly<Record<L, number>>;
1852
- }
1853
-
1854
- /** A choice among labels. Each label maps to what it means; an empty string leaves it open. */
1855
- export declare interface JevChoiceQuestion<L extends string = string> {
1856
- readonly type: "choice";
1857
- readonly instructions: string;
1858
- readonly criteria: Readonly<Record<L, string>>;
1859
- }
1860
-
1861
- /** One answered request: every asked question has an answer of its own kind. */
1862
- export declare interface JevClassification<Q extends JevQuestions = JevQuestions> {
1863
- /** The Jev model the host asked. */
1864
- readonly model: string;
1865
- readonly answers: {
1866
- readonly [K in keyof Q]: JevAnswerFor<Q[K]>;
1867
- };
1868
- /** Token counts, when the route reported them. */
1869
- readonly usage?: {
1870
- readonly inputTokens: number;
1871
- readonly outputTokens: number;
1872
- };
1873
- }
1874
-
1875
- export declare interface JevClassifyRequest<Q extends JevQuestions = JevQuestions> {
1876
- readonly state: JevState;
1877
- readonly questions: Q;
1878
- }
1879
-
1880
- /**
1881
- * The Jev client a `use` body receives. `classify` either resolves with an answer for every
1882
- * asked question, each of its question's kind, or rejects with a {@link JevCallError}; it never
1883
- * resolves with a partial or substituted answer.
1884
- */
1885
- export declare interface JevClient {
1886
- classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
1887
- readonly signal?: AbortSignal;
1888
- }): Promise<JevClassification<Q>>;
1889
- }
1890
-
1891
- export declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
1892
-
1893
- /** A rubric: questions keyed by the name each answer comes back under. */
1894
- export declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
1895
-
1896
- export declare interface JevScoreAnswer {
1897
- readonly type: "score";
1898
- /** The expected score, from 0 to the number of rungs minus one. */
1899
- readonly score: number;
1900
- readonly confidence: number;
1901
- }
1902
-
1903
- /** A score over ordered rungs: the first criterion scores 0, the next 1, and so on. */
1904
- export declare interface JevScoreQuestion {
1905
- readonly type: "score";
1906
- readonly instructions: string;
1907
- readonly criteria: readonly string[];
1908
- }
1909
-
1910
- /**
1911
- * ---
1912
- * responsibility: The plugin-facing CONTRACT for Jev typed-decision inference — the shape of
1913
- * `api.withJev` on both plugin SDK targets, the {@link JevClient} a `use` body receives, the
1914
- * question and answer vocabulary it speaks, and the fallback-only implementation a host
1915
- * without a Jev lane binds.
1916
- * owns:
1917
- * - {@link WithJev}, {@link WithJevOptions}, {@link createFallbackOnlyWithJev}.
1918
- * - {@link JevClient}, the {@link JevQuestion} and {@link JevAnswer} vocabulary, and
1919
- * {@link JevCallError}.
1920
- * does_not_own:
1921
- * - The wire. The host serves `classify` over whichever route the user's Jev provider order
1922
- * picks; a plugin never sees a vendor client, a vendor type, or a route.
1923
- * - Credential resolution, the `jev.use` decision, the Jev-branch budget, or usage accounting.
1924
- * Those are host-side (`@bonsai/agent-runtime`'s `kay/jev/`).
1925
- * ---
1926
- *
1927
- * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
1928
- * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
1929
- * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
1930
- * criterion is text, and the state is a JSON object.
1931
- */
1932
- /**
1933
- * The state a rubric reads: a JSON object, never text or an array. Every value must survive
1934
- * `JSON.stringify` unchanged (no functions or class instances), because it is sent as JSON.
1935
- * Typed as `object` so a state declared as an interface fits without an index signature.
1936
- */
1937
- export declare type JevState = object;
1938
-
1939
- /** The route a Jev call took: the user's own TypeSafe key, or Bonsai's hosted gateway. */
1940
- export declare type JevTransport = "direct" | "hosted";
1941
-
1942
1789
  declare type JsonObject = {
1943
1790
  [key: string]: JsonValue_4;
1944
1791
  };
@@ -3263,12 +3110,28 @@ export declare interface KayAppCorpusSession {
3263
3110
  * is unknown, not `user`.
3264
3111
  */
3265
3112
  readonly origin?: KayAppSessionOrigin | undefined;
3113
+ /** Resolved session title from the live index, when one exists. */
3114
+ readonly title?: string | undefined;
3115
+ /** Session creation time in ISO-8601 UTC, when the index has it. */
3116
+ readonly createdAt?: string | undefined;
3117
+ /** Last conversation activity in ISO-8601 UTC, when the index has it. */
3118
+ readonly updatedAt?: string | undefined;
3119
+ /** Current execution directory, when the index has it. */
3120
+ readonly cwd?: string | undefined;
3121
+ /** Persisted project binding; `null` means explicitly unassigned. */
3122
+ readonly projectId?: string | null | undefined;
3123
+ /** Parent session for a spawned member, when lineage is indexed. */
3124
+ readonly parentSessionId?: string | null | undefined;
3125
+ /** Family root session identity, when lineage is indexed. */
3126
+ readonly rootSessionId?: string | undefined;
3266
3127
  }
3267
3128
 
3268
3129
  /** Cheap identity for the current contents of one stored session transcript. */
3269
3130
  export declare interface KayAppCorpusSourceMark {
3270
3131
  readonly mtimeMs: number;
3271
3132
  readonly sizeBytes: number;
3133
+ /** Opaque content/source identity; absent on legacy or test corpus implementations. */
3134
+ readonly sourceRevision?: string | undefined;
3272
3135
  }
3273
3136
 
3274
3137
  /** A newly persisted AgentSession. */
@@ -4043,35 +3906,24 @@ export declare interface KayAppPluginApi {
4043
3906
  readonly config?: KayAppConfig;
4044
3907
  /** Current plugin-safe model metadata from the host's model catalog. */
4045
3908
  readonly models: KayAppModels;
4046
- /**
4047
- * Jev typed-decision inference, as an OPTIONAL accelerator with a REQUIRED fallback. Each call
4048
- * is checked against `jev.use` — but a refused grant or no usable Jev provider both
4049
- * produce the same outcome: your `fallback` runs.
4050
- *
4051
- * Always present, on every host, unlike the grant-gated and host-fact-gated members above. That
4052
- * is the point: with no absent state to feature-detect, there is no shape of code that reaches
4053
- * Jev without having written the baseline too. Do not guard it with
4054
- * `if (app.withJev !== undefined)`.
4055
- */
4056
- readonly withJev: WithJev;
4057
3909
  /**
4058
3910
  * System One: fast, cheap judgment calls (`decide`) and typed field extraction (`extract`) on
4059
- * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `jev.use`; a call
4060
- * that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
3911
+ * small models (Jev, Clef, Clef Flash, Clairic). Each call is checked against `systemOne.use`; a
3912
+ * call that cannot be served or is not permitted throws a `SystemOneError` whose `cause.kind` says
4061
3913
  * why, so put the feature's cheaper path in the call's own `catch`. Always present, on every
4062
3914
  * host. Types: `@bonsai/plugin-sdk/system-one` (SDK 0.13.8).
4063
3915
  */
4064
3916
  readonly systemOne: SystemOneClient;
4065
3917
  /**
4066
3918
  * Recorded Jev signals. `observe` runs a Jev inference and records the answer as a durable,
4067
- * provenance-stamped row; each call is checked against `jev.use`, and a refused grant, no
3919
+ * provenance-stamped row; each call is checked against `systemOne.use`, and a refused grant, no
4068
3920
  * usable Jev provider, a timeout, or a vendor error all produce the same outcome: an
4069
3921
  * `unavailable` observation with `stored: false`. A name that breaks the recorded-name grammar
4070
3922
  * is refused as `invalid` before any of that. `list` and `listDetectors` read EVERY plugin's
4071
3923
  * recorded signals back, each call checked against `signals.read`, answering `unavailable` or
4072
3924
  * `invalid` instead of rejecting. While the plugin is enabled, no call here rejects; after it is
4073
3925
  * disabled, a kept handle's `list` and `listDetectors` throw synchronously. Always present, on
4074
- * every host, for the same reason `withJev` is: no shape of code should reach Jev without a
3926
+ * every host, for the same reason `systemOne` is: no shape of code should reach Jev without a
4075
3927
  * defined baseline beside it.
4076
3928
  */
4077
3929
  readonly signals: KayAppSignals;
@@ -4812,6 +4664,96 @@ export declare interface KayAppSessionSummary {
4812
4664
  readonly provenance?: KayAppSessionProvenanceRecord | undefined;
4813
4665
  }
4814
4666
 
4667
+ export declare interface KayAppSessionSummaryChunk {
4668
+ readonly goal: string;
4669
+ readonly work: readonly string[];
4670
+ readonly decisions: readonly string[];
4671
+ readonly outcomes: readonly string[];
4672
+ readonly openWork: readonly string[];
4673
+ }
4674
+
4675
+ export declare interface KayAppSessionSummaryContinuation {
4676
+ readonly version: typeof SUMMARY_VERSION;
4677
+ readonly sessionId: string;
4678
+ readonly sourceRevision: string;
4679
+ readonly phase: "read" | "reduce";
4680
+ readonly cursor?: JsonValue;
4681
+ readonly chunks: readonly KayAppSessionSummaryChunk[];
4682
+ readonly facts: KayAppSessionSummaryFacts;
4683
+ readonly lineage: readonly KayAppSessionSummaryLineageEntry[];
4684
+ readonly pending?: KayAppSessionSummaryPending;
4685
+ readonly reduction?: KayAppSessionSummaryReduction;
4686
+ }
4687
+
4688
+ export declare type KayAppSessionSummaryCoverage = "complete" | "partial" | "unavailable" | "changed" | "missing";
4689
+
4690
+ export declare interface KayAppSessionSummaryFacts {
4691
+ readonly entryCount: number;
4692
+ readonly userTexts: readonly string[];
4693
+ readonly assistantTexts: readonly string[];
4694
+ readonly toolOutcomes: readonly string[];
4695
+ readonly resources: readonly KayAppSessionSummaryResource[];
4696
+ readonly clipped: boolean;
4697
+ readonly lineageOverflow: boolean;
4698
+ readonly malformedRecords: number;
4699
+ readonly oversizedRecords: number;
4700
+ }
4701
+
4702
+ export declare interface KayAppSessionSummaryLineageEntry {
4703
+ readonly id: string;
4704
+ /** Original transcript entry id for a bounded text segment. */
4705
+ readonly sourceId?: string;
4706
+ readonly parentId: string | null;
4707
+ readonly seq: number;
4708
+ readonly role: string;
4709
+ readonly kind: string;
4710
+ readonly text: string;
4711
+ readonly toolName?: string;
4712
+ readonly outcome?: string;
4713
+ readonly resources: readonly KayAppSessionSummaryResource[];
4714
+ }
4715
+
4716
+ export declare interface KayAppSessionSummaryPending {
4717
+ readonly startIndex: number;
4718
+ readonly endIndex: number;
4719
+ readonly nextIndex: number;
4720
+ readonly cursor: JsonValue;
4721
+ readonly status: "complete" | "more" | "awaiting-append" | "record-too-large";
4722
+ }
4723
+
4724
+ export declare interface KayAppSessionSummaryReduction {
4725
+ readonly phase: "map" | "reduce";
4726
+ readonly sourceIndex: number;
4727
+ readonly queue: readonly KayAppSessionSummaryChunk[];
4728
+ }
4729
+
4730
+ export declare interface KayAppSessionSummaryResource {
4731
+ readonly uri: string;
4732
+ readonly title: string;
4733
+ readonly entryId: string;
4734
+ }
4735
+
4736
+ export declare interface KayAppSessionSummaryResult {
4737
+ readonly summaryVersion: number;
4738
+ readonly sessionId: string;
4739
+ readonly sourceRevision: string;
4740
+ readonly coverage: KayAppSessionSummaryCoverage;
4741
+ readonly summary: KayAppSessionWorkSummary;
4742
+ readonly resources: readonly KayAppSessionSummaryResource[];
4743
+ readonly modelCalls: number;
4744
+ /** Present for unavailable coverage, bounded to 600 characters. */
4745
+ readonly unavailableReason?: string;
4746
+ readonly continuation?: KayAppSessionSummaryContinuation;
4747
+ }
4748
+
4749
+ export declare interface KayAppSessionWorkSummary {
4750
+ readonly goal: string;
4751
+ readonly work: readonly string[];
4752
+ readonly decisions: readonly string[];
4753
+ readonly outcomes: readonly string[];
4754
+ readonly openWork: readonly string[];
4755
+ }
4756
+
4815
4757
  /** One stored signal: the answers exactly as Jev gave them, and where the observed turn is. */
4816
4758
  export declare interface KayAppSignal {
4817
4759
  /** Recording order: a higher id was recorded later. */
@@ -4838,8 +4780,8 @@ export declare interface KayAppSignal {
4838
4780
  readonly inputDigest: string;
4839
4781
  }
4840
4782
 
4841
- /** One stored answer: a {@link JevAnswer}, or a yes/no answer recorded before SDK 0.12.0. */
4842
- export declare type KayAppSignalAnswer = JevAnswer | KayAppSignalNoulAnswer;
4783
+ /** One stored answer: a {@link DecideAnswer}, or a yes/no answer recorded before SDK 0.12.0. */
4784
+ export declare type KayAppSignalAnswer = DecideAnswer | KayAppSignalNoulAnswer;
4843
4785
 
4844
4786
  /** One version of one detector, under one rubric, as the catalog lists it. */
4845
4787
  export declare interface KayAppSignalDetector {
@@ -4868,7 +4810,7 @@ export declare interface KayAppSignalNoulAnswer {
4868
4810
  /**
4869
4811
  * The result of one observe call. `status` is the only field a caller must switch on:
4870
4812
  *
4871
- * - `classified`: Jev answered; `answers` (one {@link JevAnswer} per question), `model`, and
4813
+ * - `classified`: Jev answered; `answers` (one {@link DecideAnswer} per question), `model`, and
4872
4814
  * `usage` are what the Jev call returned, and `stored` says whether the row landed in the
4873
4815
  * durable store.
4874
4816
  * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
@@ -4917,6 +4859,25 @@ export declare interface KayAppSignalObservation {
4917
4859
  readonly recordedAtMs: number;
4918
4860
  }
4919
4861
 
4862
+ /** Per-call knobs for {@link KayAppSignals.observe}. Every field is optional; the host applies its
4863
+ * own default budget when none is given, so the Jev branch is never unbounded. */
4864
+ export declare interface KayAppSignalObserveOptions {
4865
+ /**
4866
+ * Explicit cancellation. Always propagates as a rejection, because an aborted call means
4867
+ * "stop", not "record nothing and carry on".
4868
+ */
4869
+ readonly signal?: AbortSignal;
4870
+ /** Bounds the Jev branch alone, measured from the call. */
4871
+ readonly timeoutMs?: number;
4872
+ /**
4873
+ * Absolute epoch-ms hard deadline for the whole call. A deadline already passed rejects (like
4874
+ * `signal`); one still ahead derives the Jev branch's budget from it.
4875
+ */
4876
+ readonly deadlineAt?: number;
4877
+ /** Attribution slug for host usage accounting. Never sent to Jev. */
4878
+ readonly purpose?: string;
4879
+ }
4880
+
4920
4881
  /** One page of signals, oldest recorded first. */
4921
4882
  export declare interface KayAppSignalPage {
4922
4883
  readonly signals: readonly KayAppSignal[];
@@ -5081,7 +5042,7 @@ export declare interface KayAppSignalsObserveInput {
5081
5042
  * transcript the source points at. So the projection must be a pure function of the
5082
5043
  * transcript and the detector version, or the row's evidence cannot be reproduced.
5083
5044
  */
5084
- readonly state: JevState;
5045
+ readonly state: KayAppSignalState;
5085
5046
  /**
5086
5047
  * The typed questions to answer. Stored once per digest. A
5087
5048
  * rubric asks 1 to 64 questions. Each name is an identifier (letters, digits, and `_`, not
@@ -5090,8 +5051,8 @@ export declare interface KayAppSignalsObserveInput {
5090
5051
  * characters with no `,`, `@`, or control or invisible character (`\p{C}`), and no whitespace
5091
5052
  * but single spaces between words, so a reader can copy it back exactly from rendered text.
5092
5053
  */
5093
- readonly questions: JevQuestions;
5094
- readonly options?: WithJevOptions;
5054
+ readonly questions: DecideQuestions;
5055
+ readonly options?: KayAppSignalObserveOptions;
5095
5056
  }
5096
5057
 
5097
5058
  /**
@@ -5172,6 +5133,9 @@ export declare interface KayAppSignalsSessionQuery {
5172
5133
  readonly limit?: number;
5173
5134
  }
5174
5135
 
5136
+ /** The state a signal's questions are asked over: any object, projected from the transcript. */
5137
+ export declare type KayAppSignalState = object;
5138
+
5175
5139
  /**
5176
5140
  * What a signal is about, named by the recording plugin. The host stores both values and never
5177
5141
  * interprets them. A signal recorded without a subject has none; every reader treats it as before.
@@ -8572,6 +8536,17 @@ declare type SubagentResultMessage = CustomMessage<SubagentResultDetails> & {
8572
8536
  readonly display: boolean;
8573
8537
  };
8574
8538
 
8539
+ export declare interface SummarizeSessionInput {
8540
+ readonly corpus: KayAppCorpus;
8541
+ readonly models: KayAppModels;
8542
+ readonly sessionId: string;
8543
+ readonly previous?: KayAppSessionSummaryResult;
8544
+ readonly maxModelCalls?: number;
8545
+ readonly signal?: AbortSignal;
8546
+ }
8547
+
8548
+ declare const SUMMARY_VERSION: 4;
8549
+
8575
8550
  /** Creates a Symbol type. */
8576
8551
  declare function Symbol_2(options?: TSchemaOptions): TSymbol;
8577
8552
 
@@ -13851,53 +13826,6 @@ declare const WithElementList_0: (input: string, result?: unknown[]) => [unknown
13851
13826
 
13852
13827
  declare function WithElementListMapping(input: [unknown, unknown, unknown] | []): unknown;
13853
13828
 
13854
- /**
13855
- * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
13856
- * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
13857
- * one: `fallback` is required, and it runs whenever no provider in the user's Jev provider
13858
- * order holds a usable credential, the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
13859
- * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
13860
- * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
13861
- *
13862
- * ALWAYS PRESENT on the plugin API, on every host. A host that composed no Jev lane binds
13863
- * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
13864
- * exactly how a fallback gets skipped.
13865
- *
13866
- * `jev` is a {@link JevClient} on the host's Jev model. It is valid only for the duration of
13867
- * the callback: a reference retained past `use`'s scope is refused at the transport, and an
13868
- * in-flight request is aborted when the call stops waiting.
13869
- * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
13870
- * that is already running, so `use` must not perform side effects it would mind completing
13871
- * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
13872
- * cannot interrupt its JavaScript.
13873
- */
13874
- export declare type WithJev = <T>(
13875
- /** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
13876
- * `undefined` should return `null` or its own wrapper type instead. */
13877
- use: (jev: JevClient) => T | undefined | PromiseLike<T | undefined>,
13878
- /** Required. The behaviour the feature has without Jev. */
13879
- fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;
13880
-
13881
- /** Per-call knobs for {@link WithJev}. Every field is optional; the host applies its own default
13882
- * budget when none is given, so the Jev branch is never unbounded. */
13883
- export declare interface WithJevOptions {
13884
- /**
13885
- * Explicit cancellation. Always propagates as a rejection; never substituted with `fallback`,
13886
- * because an aborted call means "stop", not "use the cheaper path".
13887
- */
13888
- readonly signal?: AbortSignal;
13889
- /** Bounds the Jev branch alone, measured from the call. */
13890
- readonly timeoutMs?: number;
13891
- /**
13892
- * Absolute epoch-ms hard deadline for the WHOLE call, `fallback` included. A deadline already
13893
- * passed rejects (like `signal`); one still ahead derives the Jev branch's budget from it and
13894
- * keeps a small reserve so `fallback` has a window to run.
13895
- */
13896
- readonly deadlineAt?: number;
13897
- /** Attribution slug for host usage accounting. Never sent to Jev. */
13898
- readonly purpose?: string;
13899
- }
13900
-
13901
13829
  declare function WithMapping(input: [unknown, unknown] | []): unknown;
13902
13830
 
13903
13831
  declare const WithNull: (input: string) => [unknown, string] | [];
package/dist/kay-app.js CHANGED
@@ -11,80 +11,6 @@ var JsonValue = z.lazy(() => z.union([
11
11
  var JsonObject = z.record(z.string(), JsonValue);
12
12
  var JsonSchema = z.record(z.string(), JsonValue);
13
13
 
14
- // packages/plugin-sdk/dist/jev.js
15
- var JevCallError = class extends Error {
16
- transport;
17
- kind;
18
- /** The final attempt's HTTP status, when a response arrived. */
19
- status;
20
- constructor(init) {
21
- super(`Jev call failed on the ${init.transport} route: ${init.kind}${init.status === void 0 ? "" : ` (HTTP ${init.status})`}.`);
22
- this.name = "JevCallError";
23
- this.transport = init.transport;
24
- this.kind = init.kind;
25
- this.status = init.status;
26
- }
27
- };
28
- function createFallbackOnlyWithJev() {
29
- return async (_use, fallback, options = {}) => {
30
- if (typeof fallback !== "function") {
31
- throw new TypeError("withJev requires a `fallback` function as its second argument.");
32
- }
33
- const { signal, deadlineAt } = options;
34
- if (deadlineAt !== void 0 && !Number.isFinite(deadlineAt)) {
35
- throw new TypeError("withJev's `deadlineAt` must be a finite epoch-ms timestamp.");
36
- }
37
- const assertWithinBoundaries = () => {
38
- if (signal?.aborted === true) {
39
- throw signal.reason ?? new DOMException("Aborted", "AbortError");
40
- }
41
- if (deadlineAt !== void 0 && Date.now() >= deadlineAt) {
42
- throw new Error("withJev's deadline has passed.");
43
- }
44
- };
45
- assertWithinBoundaries();
46
- let timer;
47
- let onAbort;
48
- const stopped = new Promise((_resolve, reject) => {
49
- if (signal !== void 0) {
50
- onAbort = () => reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
51
- signal.addEventListener("abort", onAbort, { once: true });
52
- }
53
- if (deadlineAt !== void 0) {
54
- const checkDeadline = () => {
55
- const remaining = deadlineAt - Date.now();
56
- if (remaining <= 0) {
57
- reject(new Error("withJev's deadline has passed."));
58
- } else {
59
- timer = setTimeout(checkDeadline, Math.min(remaining, 2147483647));
60
- }
61
- };
62
- checkDeadline();
63
- }
64
- });
65
- try {
66
- const result = await Promise.race([
67
- Promise.resolve().then(() => {
68
- assertWithinBoundaries();
69
- return fallback();
70
- }),
71
- stopped
72
- ]);
73
- assertWithinBoundaries();
74
- return result;
75
- } catch (error) {
76
- assertWithinBoundaries();
77
- throw error;
78
- } finally {
79
- if (timer !== void 0)
80
- clearTimeout(timer);
81
- if (signal !== void 0 && onAbort !== void 0) {
82
- signal.removeEventListener("abort", onAbort);
83
- }
84
- }
85
- };
86
- }
87
-
88
14
  // packages/plugin-sdk/dist/signals.js
89
15
  import { z as z2 } from "zod";
90
16
  function createFallbackOnlySignals() {
@@ -92,7 +18,7 @@ function createFallbackOnlySignals() {
92
18
  return {
93
19
  observe: (input) => Promise.resolve(invalidObservation(input) ?? {
94
20
  status: "unavailable",
95
- reason: "no-jev-lane",
21
+ reason: "no-system-one",
96
22
  detector: { ...input.detector, rubricDigest: "" },
97
23
  source: input.source,
98
24
  stored: false,
@@ -591,7 +517,6 @@ var KAY_APP_DATA_CHANGE_MAX_BYTES = 256 * 1024;
591
517
  var KAY_APP_DATA_READ_REQUEST_MAX_BYTES = 64 * 1024;
592
518
  var KAY_APP_DATA_READ_RESULT_MAX_BYTES = 16 * 1024 * 1024;
593
519
  export {
594
- JevCallError,
595
520
  JsonSchema,
596
521
  JsonValue,
597
522
  KAY_APP_AUTOMATION_CONDITION_KINDS,
@@ -606,7 +531,6 @@ export {
606
531
  UriUnsupportedOperationError,
607
532
  UriValidationError,
608
533
  createFallbackOnlySignals,
609
- createFallbackOnlyWithJev,
610
534
  createUnavailableSkills,
611
535
  createUnavailableTools,
612
536
  createUnavailableUsage,