@neosh/api 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@neosh/api",
+  "version": "0.1.0",
+  "description": "The neosh plugin API. Types are generated from the Rust side and drift-checked in CI.",
+  "license": "MIT",
+  "type": "module",
+  "types": "src/index.ts",
+  "exports": { ".": "./src/index.ts" },
+  "keywords": [
+    "neosh",
+    "neosh-plugin",
+    "agent",
+    "typescript"
+  ],
+  "homepage": "https://github.com/neoswarm/neosh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neoswarm/neosh.git",
+    "directory": "plugins/api"
+  },
+  "files": [
+    "src",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/src/generated/AccountKind.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * What you are spending when you use an instance.
+ *
+ * The one distinction the old flat list could not make. Everything else in a picker — ordering,
+ * grouping, which sign-in verb to offer, whether to show a price — follows from this.
+ */
+export type AccountKind = "plan" | "api_key" | "local";

package/src/generated/Activity.ts

@@ -0,0 +1,85 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { BackgroundTask } from "./BackgroundTask";
+import type { DriverCommand } from "./DriverCommand";
+import type { PlanStep } from "./PlanStep";
+import type { QuotaCredits } from "./QuotaCredits";
+import type { QuotaWindow } from "./QuotaWindow";
+import type { TaskId } from "./TaskId";
+import type { TaskStatus } from "./TaskStatus";
+import type { ToolCallId } from "./ToolCallId";
+import type { Usage } from "./Usage";
+
+/**
+ * Something the driver's own loop did that is not part of the message it is producing.
+ *
+ * [`ProviderEvent`] mirrors the Messages SSE shape, and for a model driver that is the whole
+ * story: a model emits content blocks and nothing else. An agent driver is *running a loop* — it
+ * spawns sub-agents, keeps a plan, compacts its own context, and knows which commands it will
+ * accept. None of that is a content block, and the two ways to force it into one are both bad:
+ * invent assistant text nobody wrote, or drop it. neosh dropped it, in one line
+ * (`sse.rs`: *"non-model event families must be ignored"*), which is why a running sub-agent was
+ * invisible and `/compact` looked like a hang.
+ *
+ * This is a decision about **shape, not access**. Every one of these already arrives on the
+ * transport the driver uses — for `claude` they are `{"type":"system",…}` lines on the same stdout
+ * the content blocks come down, and `Plan` is read out of an ordinary `TodoWrite` call. Nothing
+ * here needs a privileged channel; it needed somewhere to go.
+ */
+export type Activity =
+  | {
+    "kind": "task_started";
+    task: TaskId;
+    /**
+     * What it was asked to do, in one line.
+     */
+    title: string;
+    /**
+     * Which kind of sub-agent, when the driver distinguishes them.
+     */
+    role?: string | null;
+    /**
+     * The call that spawned it, when a call did. Absent for a task the driver started on its
+     * own — a background job, a member of a workflow.
+     */
+    parent_call?: ToolCallId | null;
+    model?: string | null;
+    /**
+     * Whether it was let go of at the moment it started, rather than the turn blocking on it.
+     *
+     * A shell launched detached and a sub-agent spawned into the background both arrive this
+     * way. The *later* move to the background arrives as a status change instead, which is
+     * the case that was already handled — so without this the two halves of one idea were
+     * read in two different places and the commoner half was the one that was missed.
+     */
+    backgrounded: boolean;
+  }
+  | {
+    "kind": "task_progress";
+    task: TaskId;
+    summary?: string | null;
+    /**
+     * The last tool it called, which is the cheapest possible "it is not stuck".
+     */
+    last_tool?: string | null;
+    usage: Usage;
+  }
+  | {
+    "kind": "task_ended";
+    task: TaskId;
+    status: TaskStatus;
+    summary?: string | null;
+  }
+  | { "kind": "background"; tasks: Array<BackgroundTask> }
+  | { "kind": "plan"; steps: Array<PlanStep> }
+  | { "kind": "waiting"; what: string; retry_in_ms?: number | null }
+  | { "kind": "compacting" }
+  | { "kind": "compacted"; before?: number | null; after?: number | null }
+  | { "kind": "commands"; commands: Array<DriverCommand> }
+  | { "kind": "resume"; token: string }
+  | { "kind": "context"; used: number; total: number }
+  | {
+    "kind": "quota";
+    plan?: string | null;
+    windows: Array<QuotaWindow>;
+    credits?: QuotaCredits | null;
+  };

package/src/generated/AgentCommand.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 { PermissionDecision } from "./PermissionDecision";
+
+/**
+ * What a node can be asked to do with an agent it owns.
+ *
+ * Every one is a *request*. The owner decides — it may be busy, the conversation may have been
+ * deleted a moment ago, or the person sitting at it may have said no to remote control entirely.
+ * A command that could not be refused would make every node an administrator of every other one.
+ */
+export type AgentCommand =
+  | { "command": "send"; text: string }
+  | { "command": "interrupt" }
+  | { "command": "approve"; decision: PermissionDecision }
+  | { "command": "set_model"; instance: string; model: string }
+  | { "command": "rename"; title: string | null }
+  | { "command": "archive"; archived: boolean }
+  | { "command": "new_session"; cwd?: string | null; title?: string | null };

package/src/generated/AgentState.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.
+
+/**
+ * What an agent is doing, coarsely enough to be worth sending on every change.
+ */
+export type AgentState = "idle" | "running" | "blocked" | "failed";

package/src/generated/AgentSummary.ts

@@ -0,0 +1,46 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { AgentState } from "./AgentState";
+import type { ProjectKey } from "./ProjectKey";
+import type { SessionId } from "./SessionId";
+import type { Usage } from "./Usage";
+
+/**
+ * One agent, as another node sees it.
+ *
+ * A description, not a handle. Everything here is for showing and for deciding what to ask; acting
+ * on it means sending a [`Command`](AscpMessage::Command) to the node that owns it.
+ */
+export type AgentSummary = {
+  /**
+   * The conversation id, which is unique on its own node and nowhere else. Address an agent as
+   * `(node, id)`; two machines restoring from the same backup would otherwise be one collision
+   * away from steering each other's work.
+   */
+  session: SessionId;
+  project: ProjectKey;
+  /**
+   * What that node calls the project — `neosh`, or `neosh · fix/thing` for a worktree.
+   */
+  project_name: string;
+  /**
+   * The working directory **on the owning node**. Shown, never opened: it is a path in somebody
+   * else's filesystem and may not exist here at all.
+   */
+  cwd: string;
+  /**
+   * The title, or the opening of the first message. Computed by the owner so every node agrees.
+   */
+  label: string;
+  state: AgentState;
+  message_count: number;
+  /**
+   * The model the owner will use for the next turn, for a board that says so.
+   */
+  model?: string | null;
+  /**
+   * Seconds since the epoch, when the running turn began. Only meaningful while `Running`.
+   */
+  turn_started_at?: number | null;
+  updated_at: number;
+  usage: Usage;
+};

package/src/generated/Anchor.ts

@@ -0,0 +1,12 @@
+// 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 { WindowId } from "./WindowId";
+
+/**
+ * What a float is positioned relative to.
+ */
+export type Anchor =
+  | { "kind": "cursor" }
+  | { "kind": "window"; win: WindowId }
+  | { "kind": "screen" }
+  | { "kind": "dock"; dock: Dock };

package/src/generated/Animation.ts

@@ -0,0 +1,40 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FrameSet } from "./FrameSet";
+
+/**
+ * Text that moves on its own.
+ *
+ * Declared on a highlight group rather than driven by whoever wrote the text, for two reasons.
+ * A plugin animating text itself would have to re-set an extmark per character per tick — forty
+ * API calls at 20 Hz, across a runtime boundary, to move a highlight two columns. And motion is a
+ * *display* decision: how bright a band can get depends on what the terminal can render, which is
+ * the one thing only the frontend knows.
+ *
+ * So the core stores this and forwards it; the frontend animates whatever carries it, at whatever
+ * rate it likes, and stops when nothing animated is on screen. Nothing wakes the core.
+ */
+export type Animation =
+  | {
+    "kind": "shimmer";
+    /**
+     * One full sweep, in milliseconds.
+     */
+    period_ms: number;
+  }
+  | { "kind": "pulse"; period_ms: number }
+  | {
+    "kind": "frames";
+    set: FrameSet;
+    /**
+     * One full cycle through the set, in milliseconds.
+     */
+    period_ms: number;
+  }
+  | {
+    "kind": "flash";
+    /**
+     * How long the lift takes to fall back to nothing.
+     */
+    ms: number;
+  }
+  | { "kind": "spectrum"; period_ms: number };