@neosh/api 0.1.0

package/src/generated/UsageBucket.ts

@@ -0,0 +1,32 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { CostBasis } from "./CostBasis";
+import type { InstanceId } from "./InstanceId";
+import type { Usage } from "./Usage";
+
+/**
+ * One `(bucket, instance, model)` cell of history.
+ *
+ * The cost is what these tokens *would* have cost at API rates. It is not money spent: a
+ * subscription bills separately and a plan turn costs nothing extra at all. It is here because it
+ * is the only common unit that lets Opus and Haiku appear on one axis.
+ */
+export type UsageBucket = {
+  /**
+   * Unix seconds at the start of the bucket, in the zone the request asked for.
+   */
+  start: number;
+  instance: InstanceId;
+  model: string;
+  usage: Usage;
+  cost_usd: number;
+  /**
+   * What the cached input would have cost at full input rates, minus what it did cost. The
+   * difference between a conversation that is expensive and one that only looks it.
+   */
+  cache_savings_usd: number;
+  basis: CostBasis;
+  /**
+   * Distinct assistant responses, after de-duplication.
+   */
+  requests: number;
+};

package/src/generated/UsageHistory.ts

@@ -0,0 +1,23 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { UsageBucket } from "./UsageBucket";
+import type { UsageResolution } from "./UsageResolution";
+import type { UsageScanSource } from "./UsageScanSource";
+
+/**
+ * A whole answer to "where did the week go".
+ */
+export type UsageHistory = {
+  buckets: Array<UsageBucket>;
+  sources: Array<UsageScanSource>;
+  resolution: UsageResolution;
+  since: number;
+  until: number;
+  /**
+   * Whether every model that appeared had a price. Drawn as a caveat on the cost axis.
+   */
+  fully_priced: boolean;
+  /**
+   * Wall-clock cost of the scan, so a slow answer can be explained rather than guessed at.
+   */
+  scanned_ms: number;
+};

package/src/generated/UsageResolution.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * How coarsely a history is bucketed.
+ */
+export type UsageResolution = "hour" | "day";

package/src/generated/UsageScanSource.ts

@@ -0,0 +1,24 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { InstanceId } from "./InstanceId";
+import type { UsageScanStatus } from "./UsageScanStatus";
+
+/**
+ * What one transcript directory yielded, so a client can say what it could not read.
+ *
+ * A history with a hole in it and a history that is genuinely empty look identical in the buckets,
+ * and the difference matters: one means "you did not use it", the other means "we could not tell".
+ */
+export type UsageScanSource = {
+  instance: InstanceId;
+  /**
+   * The directory that was read, for a message that names a real path.
+   */
+  path: string;
+  status: UsageScanStatus;
+  files: number;
+  /**
+   * Lines that parsed but carried nothing recognisable.
+   */
+  malformed: number;
+  message?: string | null;
+};

package/src/generated/UsageScanStatus.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type UsageScanStatus = "ok" | "missing" | "partial" | "failed";

package/src/generated/UserQuestion.ts

@@ -0,0 +1,34 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { QuestionOption } from "./QuestionOption";
+
+/**
+ * One thing an agent wants to know before it carries on, and the answers it suggests.
+ *
+ * Deliberately not a [`PermissionOption`] list. A permission request asks *may this happen* and
+ * every answer to it is a yes or a no; this asks *which of these* — several times over, sometimes
+ * with more than one answer each, sometimes with an answer nobody listed. Squeezing it into the
+ * permission family would mean a prompt whose "options" are not decisions about the thing being
+ * asked, and a policy layer that could answer `full access` to a question about which database to
+ * use.
+ */
+export type UserQuestion = {
+  /**
+   * The question, and its identity.
+   *
+   * One field for both on purpose. The `claude` CLI looks an answer up *by the text of the
+   * question it answers* — the reply is a map keyed on this string — so a generated id would be
+   * an answer to a question that does not exist, and the turn would come back saying nobody
+   * answered. Whatever asks, the rule is the same: the question is the key.
+   */
+  question: string;
+  /**
+   * Two or three words over the question — `Auth method`, `Library`, `Approach`. A chip rather
+   * than a sentence, and it is what a folded card says the question was about.
+   */
+  header: string;
+  options: Array<QuestionOption>;
+  /**
+   * Whether more than one option may be taken.
+   */
+  multi_select: boolean;
+};

package/src/generated/VarScope.ts

@@ -0,0 +1,18 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BufferId } from "./BufferId";
+import type { SessionId } from "./SessionId";
+import type { WindowId } from "./WindowId";
+
+/**
+ * What a shared variable is *about*.
+ *
+ * Deliberately not a free-form string. A scope that was `"project:/home/me/x"` would be one typo
+ * away from a value nothing ever reads again, and the host is the only thing that can say whether a
+ * conversation still exists — which is what lets it throw away the vars of one that does not.
+ */
+export type VarScope =
+  | { "scope": "global" }
+  | { "scope": "session"; session: SessionId }
+  | { "scope": "project"; cwd: string }
+  | { "scope": "buffer"; buf: BufferId }
+  | { "scope": "window"; win: WindowId };

package/src/generated/ViewId.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One attached terminal.
+ *
+ * A workspace can have several, and they are not copies of each other: a window belongs to
+ * exactly one, so the conversation on screen, the scroll position, the composer and the
+ * panels open over it are all facts about a view rather than about the workspace. Buffers are
+ * not — what the agent produced is the workspace's, and a conversation shown in two terminals
+ * is one transcript with two cursors on it.
+ *
+ * On the wire because a plugin has to be able to say which terminal it is drawing into. It
+ * was kept out of the protocol deliberately at first, when every view saw the same frame and
+ * the number bought nothing; a float that must land in *this* terminal is what changed.
+ */
+export type ViewId = number;

package/src/generated/ViewInfo.ts

@@ -0,0 +1,23 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { SessionId } from "./SessionId";
+import type { ViewId } from "./ViewId";
+
+/**
+ * One terminal looking at this workspace.
+ *
+ * A view is a set of windows: the conversation on screen, how far up it you have read, the
+ * composer, the panels open over it. Buffers are not — what the agent produced is the workspace's
+ * — so a conversation open in two terminals is one conversation with two places to be in it.
+ */
+export type ViewInfo = {
+  view: ViewId;
+  /**
+   * The conversation on screen here.
+   */
+  session: SessionId;
+  /**
+   * Whether this is the terminal being served — the one whose key press is running, or whose
+   * turn it is to be drawn into.
+   */
+  current: boolean;
+};

package/src/generated/Viewport.ts

@@ -0,0 +1,18 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A window's resolved geometry.
+ */
+export type Viewport = {
+  width: number;
+  height: number;
+  top_line: number;
+  /**
+   * Buffer rows actually on the screen, which on a wrapping window is fewer than `height`.
+   */
+  rows: number;
+  /**
+   * Lines in the buffer, so a caller can page without a second round trip.
+   */
+  line_count: number;
+};

package/src/generated/VirtChunk.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * One run of virtual text with a semantic highlight group.
+ */
+export type VirtChunk = { text: string; hl_group?: string | null };

package/src/generated/VirtTextPos.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Where virtual text is drawn relative to the line it is attached to.
+ */
+export type VirtTextPos = "right" | "eol" | "inline" | "above" | "below";

package/src/generated/WindowId.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * A viewport onto a buffer. Covers both docked windows and floats.
+ */
+export type WindowId = number;

package/src/generated/WindowInfo.ts

@@ -0,0 +1,22 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BufferId } from "./BufferId";
+import type { WindowId } from "./WindowId";
+import type { WindowLayout } from "./WindowLayout";
+
+/**
+ * A window as somebody else sees it.
+ */
+export type WindowInfo = {
+  win: WindowId;
+  buf: BufferId;
+  /**
+   * What the buffer in it declared itself to be, if anything.
+   */
+  kind?: string | null;
+  name: string;
+  layout: WindowLayout;
+  /**
+   * Whether this is the window keys are going to.
+   */
+  focused: boolean;
+};

package/src/generated/WindowLayout.ts

@@ -0,0 +1,28 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Dock } from "./Dock";
+import type { FloatConfig } from "./FloatConfig";
+import type { Gravity } from "./Gravity";
+
+/**
+ * Declarative placement for a window. The frontend turns this into a rectangle.
+ */
+export type WindowLayout = {
+  "kind": "docked";
+  dock: Dock;
+  /**
+   * Preferred extent along the dock's variable axis.
+   */
+  size?: number | null;
+  /**
+   * Which end content settles against when there is not enough of it to fill the window.
+   */
+  gravity: Gravity;
+  /**
+   * Whether long lines wrap rather than clip. The main dock always wraps; every other dock
+   * clips unless it says otherwise, because a text field is the only chrome whose content
+   * is prose. A bottom dock that wraps also grows to fit what wrapped, `size` becoming its
+   * floor — a field that wraps a long line and then hides the wrapped rows has clipped it
+   * with extra steps.
+   */
+  wrap?: boolean | null;
+} | { "kind": "float"; config: FloatConfig };

package/src/generated/WorkspaceStatus.ts

@@ -0,0 +1,28 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BuildId } from "./BuildId";
+import type { RunningTurn } from "./RunningTurn";
+
+/**
+ * What a workspace is holding, for `neosh status`.
+ */
+export type WorkspaceStatus = {
+  /**
+   * Seconds since the workspace started.
+   */
+  uptime_secs: number;
+  /**
+   * Seconds since a client was last attached, or 0 while one is.
+   */
+  idle_secs: number;
+  attached: boolean;
+  conversations: number;
+  /**
+   * One line per conversation with a turn in flight: what it is called and what it is doing.
+   */
+  running: Array<RunningTurn>;
+  /**
+   * The build the workspace is running, which is the one that started it however many times
+   * the binary has been replaced since.
+   */
+  build: BuildId;
+};

package/src/generated/WorktreeInfo.ts

@@ -0,0 +1,16 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type WorktreeInfo = {
+  path: string;
+  branch?: string | null;
+  head?: string | null;
+  /**
+   * The original checkout, as opposed to one `git worktree add` created.
+   */
+  is_main: boolean;
+  locked: boolean;
+  /**
+   * True for the worktree this neosh is running in.
+   */
+  is_current: boolean;
+};

package/src/globals.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Globals the neosh runtime installs.
+ *
+ * These are declared here rather than pulled in from `lib.dom` or `@types/node`, because neither is
+ * true: the runtime is a bare deno_core with no DOM, no filesystem and no network. Everything with
+ * an effect goes through `@neosh/api`, which is what makes hooks and permissions mean anything.
+ *
+ * Timer handles are opaque numbers. They are not Node's `Timeout` objects and have no `.unref()`.
+ */
+
+/** Run `fn` once, no sooner than `ms` from now. */
+declare function setTimeout<A extends unknown[]>(
+  fn: (...args: A) => unknown,
+  ms?: number,
+  ...args: A
+): number;
+
+/** Run `fn` repeatedly. The next firing is scheduled when the previous one is dispatched, so a slow
+ * callback cannot build up a backlog. */
+declare function setInterval<A extends unknown[]>(
+  fn: (...args: A) => unknown,
+  ms?: number,
+  ...args: A
+): number;
+
+declare function clearTimeout(id: number | undefined): void;
+declare function clearInterval(id: number | undefined): void;
+
+/** Present, and the only console there is: it routes to neosh's log file, not to the terminal —
+ * stdout belongs to the UI protocol. Prefer `neosh.log`, which is attributed to your plugin. */
+declare const console: {
+  log(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+};
+
+declare function queueMicrotask(fn: () => void): void;