@softov/ahpc 0.1.0

package/dist/src/state.d.ts

@@ -0,0 +1,355 @@
+import type { BindingPath, ReactiveStore } from '@textui/core';
+import type { HostEvent } from './ahp/connection.js';
+import type { Changeset, PendingInput, QueuedMessage, SessionSummary, Turn } from './ahp/types.js';
+/**
+ * Where the conversation lives, and how the host's actions get there.
+ *
+ * The store is the only state. Everything the host says is folded in here, and
+ * every screen reads it back out - so the transcript, the sessions list, the
+ * status bar and the composer are all looking at one answer to "what is
+ * happening", and a turn that finishes updates all four without any of them
+ * knowing the others exist.
+ *
+ * Nothing in this file renders. That is the whole point of it being a file.
+ */
+export declare const HOST: BindingPath;
+export declare const SESSIONS: BindingPath;
+/** The open conversation. One at a time, so it is not keyed by session. */
+export declare const TURNS: BindingPath;
+export declare const INPUT: BindingPath;
+export declare const CHANGES: BindingPath;
+/**
+ * What the host handed the open session: plugins, skills, MCP servers.
+ *
+ * On the conversation rather than the catalogue, because that is where the
+ * protocol puts it - two sessions on the same host, opened in different
+ * directories, are given different skills, so there is no host-wide answer to
+ * cache. Read when a panel that shows them opens.
+ */
+export declare const CUSTOMIZATIONS: BindingPath;
+/**
+ * Who else is in the open session.
+ *
+ * Host-kept membership from `SessionState.activeClients`, including this
+ * client, which adds itself on opening the view. A session nobody else is in
+ * is the ordinary case and shows nothing.
+ */
+export declare const PRESENT: BindingPath;
+/** Which file of the changeset is open, by uri. Null is the list. */
+export declare const OPEN_FILE: BindingPath;
+/**
+ * Which changesets this session offers, and which one is on screen.
+ *
+ * The session advertises several - what the conversation changed, what one
+ * turn changed, what the working tree has - and drawing the first that needs
+ * no filling in was drawing one and hiding the rest. `CHANGE_AT` is the
+ * chosen changeset's own URI, or empty for "whichever the host would pick".
+ */
+export declare const CHANGE_SCOPES: BindingPath;
+export declare const CHANGE_AT: BindingPath;
+/** The row the cursor is on, so a key can act on it. */
+export declare const CHANGE_ROW: BindingPath;
+/**
+ * Where the file browser is looking, and what it found.
+ *
+ * The host's filesystem, not this machine's. `FILES_AT` is a `file://`
+ * directory URI on the host; empty means the session's own workspace, which is
+ * the only directory a client can name without having listed something first.
+ */
+export declare const FILES_AT: BindingPath;
+export declare const FILES_ENTRIES: BindingPath;
+export declare const FILES_OPEN: BindingPath;
+/**
+ * The automations screen: what the host holds, and which row the cursor is on.
+ *
+ * The host's, not a session's - an automation outlives every session it
+ * starts, and belongs to the host the way the catalogue does.
+ */
+export declare const AUTOMATIONS: BindingPath;
+export declare const AUTOMATION_ROW: BindingPath;
+export declare const STATUS: BindingPath;
+/**
+ * Is there a turn to stop, as a `when` clause can ask it.
+ *
+ * The status is a bitset carrying client flags as well as activity - an idle
+ * session that has been read is 33 - so "status > 1" is not "something is
+ * happening", it is "something is happening, or somebody looked at it". The
+ * decoding belongs in one place, and a clause cannot call it, so the answer is
+ * written beside the number.
+ */
+export declare const RUNNING: BindingPath;
+/**
+ * What the next message will be sent as.
+ *
+ * Not a session's state, and deliberately not keyed by session: it is the
+ * composer's own row of choices, which exists before there is a session to
+ * hang them on. Sending is what turns them into one - a `createSession` with
+ * the harness and the workspace, and a `chat/turnStarted` carrying the model,
+ * because AHP hangs the model on the message rather than on the session.
+ */
+export declare const PROVIDER: BindingPath;
+export declare const MODEL: BindingPath;
+/**
+ * The answers to the chosen model's own questions.
+ *
+ * A model carries a `configSchema` and the protocol says a client presents it
+ * as a form and returns the resolved values in `ModelSelection.config`. Kept
+ * beside the model rather than in `SETTINGS`, because they are two different
+ * documents answered separately: the session's schema is the host's, this one
+ * is the model's, and a model that changes takes its answers with it.
+ */
+export declare const MODEL_CONFIG: BindingPath;
+/**
+ * The chat the open session dispatches to.
+ *
+ * A session is not a conversation - it holds chats - and the uri of the one
+ * being read is what gets pasted into a shell or a bug report. Held because
+ * only `detail` knows it, and asking again to draw a caption is a round trip
+ * for something that does not change.
+ */
+export declare const CHAT_URI: BindingPath;
+/**
+ * The open session's chats.
+ *
+ * A session is a container: it holds chats, and which of them is being read
+ * is `CHAT_URI`. One chat is the ordinary case and the row that shows this is
+ * hidden then - a list of one is a list nobody needs.
+ */
+export declare const CHATS: BindingPath;
+/**
+ * Whether the open session's agent can hold another chat.
+ *
+ * A path rather than a check, because that is what gates a command: `when`
+ * reads the store, and a host that does not advertise `multipleChats` is one
+ * where `createChat` MUST NOT be called - so the command is not offered.
+ */
+/** The terminals the host is running. The host's list, not any session's. */
+export declare const TERMINALS: BindingPath;
+/** Which of them is being read. */
+export declare const OPEN_TERMINAL: BindingPath;
+/** Its state. Null while nothing has been read yet, which is not the same as empty. */
+export declare const TERMINAL: BindingPath;
+export declare const CAN_ADD_CHAT: BindingPath;
+/**
+ * Whether this session's agent can fork a chat, and whether it can hold a side
+ * chat.
+ *
+ * Two paths rather than one, because `capabilities.multipleChats` carries the
+ * two separately and a host may advertise one without the other. A command
+ * offered where the host will refuse it is worse than one that is not there.
+ */
+export declare const CAN_FORK: BindingPath;
+export declare const CAN_SIDE_CHAT: BindingPath;
+/** Whether the open session has more than one chat to move between. */
+export declare const HAS_CHATS: BindingPath;
+export declare const WORKSPACE: BindingPath;
+/**
+ * Everything else the host asks about, keyed by the host's own keys.
+ *
+ * Not one path per setting: the settings are whatever the harness advertises,
+ * and this client had a `permissions` path because the *fixture* called its
+ * key `permissionMode`. A real host's keys are `isolation`, `autoApprove` and
+ * `mode`, so the row of chips read every one of them as absent - a control
+ * naming a key is a control that works against one host.
+ */
+export declare const SETTINGS: BindingPath;
+/** What the host last refused, in the host's own words. Cleared by success. */
+export declare const HOST_ERROR: BindingPath;
+/**
+ * What became of the answer just given, on the row above the composer.
+ *
+ * Not `HOST_ERROR`, which is the application's last refusal and lives in the
+ * footer: this is about the block that is waiting on a person, and it only
+ * ever says anything between pressing a button on that block and the host
+ * letting go of the question. Both, for a refusal of *this* - the footer is
+ * twenty rows from the button that was pressed, and a person who pressed
+ * Approve and was told nothing has no reason to look down there.
+ */
+export declare const INPUT_STATUS: BindingPath;
+/** The row's two states: gone to the host, or never going. */
+export interface InputStatus {
+    state: 'sending' | 'failed';
+    text: string;
+}
+export declare const OPEN: BindingPath;
+/** Which of the bood this run got. One animal, wherever one is drawn. */
+export declare const BOOD: BindingPath;
+/**
+ * How many rows the bottom of the screen is keeping, which is the creature's
+ * floor.
+ *
+ * Published by whatever is down there rather than assumed, because it moves:
+ * the composer grows a slash menu upward, grows again with a multi-line draft,
+ * and is not on every screen at all. A constant was wrong the moment a menu
+ * opened - the figure stood at the height the composer used to be, which is
+ * inside the menu.
+ */
+export declare const BOOD_FLOOR: BindingPath;
+/**
+ * The top row of one thing standing at the bottom, under its own name.
+ *
+ * A row and not a height, because a height has to be right and a row only has
+ * to be where the thing is. Adding up heights meant trusting each measurement
+ * and a guess at the chrome underneath them - and the block that asks about a
+ * tool reported seven rows while drawing ten, which put the creature inside
+ * the question it was supposed to be standing on.
+ *
+ * A subtree because there is more than one of them: the composer is down
+ * there, and the block that asks is a sibling above it rather than a part of
+ * it, so neither one knows the whole answer.
+ */
+export declare const boodFloorFor: (key: string) => BindingPath;
+/** The highest thing standing at the bottom, or nothing standing there. */
+export declare function boodFloor(store: ReactiveStore): number | undefined;
+/** Whether the creature roams the whole application rather than one screen. */
+export declare const BOOD_FLOAT: BindingPath;
+/** Whether the header trades its own name for a seven-cell creature. */
+export declare const BOOD_INLINE: BindingPath;
+/** The catalogue's highlight. What a session command acts on when none is open. */
+export declare const SELECTED: BindingPath;
+export declare const DRAFT: BindingPath;
+export declare const QUEUE: BindingPath;
+export declare const HISTORY: BindingPath;
+export declare const FILTER: BindingPath;
+export declare const ARCHIVED: BindingPath;
+export declare const EXPANDED: BindingPath;
+/** What is being looked for in the open conversation. Empty means nothing is. */
+export declare const FIND: BindingPath;
+/** Whether the find box is up. It stays up on an empty query, which is how it is typed into. */
+export declare const FINDING: BindingPath;
+/** Which of the matches the cursor is on, counted from zero. */
+export declare const FIND_AT: BindingPath;
+/**
+ * Which block the transcript cursor is on.
+ *
+ * In the chat screen's own scope, so it survives a trip to the changes list
+ * and dies with the screen. Named here because the find commands move it and
+ * they do not live in the screen.
+ */
+export declare const CURSOR: BindingPath;
+/**
+ * Whether what the agent said is drawn as markdown, or as what it typed.
+ *
+ * On, because an agent writes markdown and reading `**this**` is reading the
+ * punctuation instead of the sentence. Off is for the times the punctuation is
+ * the point: copying a fenced block out with the fence, seeing whether a table
+ * is a table or four lines that happen to have pipes in them, and reading a
+ * link's target rather than its label.
+ */
+export declare const MARKDOWN: BindingPath;
+/**
+ * Whether the catalogue's detail pane is out, or `null` for "whatever the
+ * terminal is wide enough for".
+ *
+ * Three states rather than two, because "nobody has said" and "somebody said
+ * no" are different: the first still follows the window as it is resized, and
+ * the second has to survive a resize or the key that closed the pane would be
+ * undone by dragging the corner.
+ */
+export declare const SIDEBAR: BindingPath;
+/**
+ * The width at which the detail pane is out to begin with.
+ *
+ * Under it the two panes are each other's problem: forty cells of detail take
+ * the session list down to a column that cuts every title, and the detail
+ * pane they were taken for is itself too narrow to hold the URIs it exists to
+ * show. So below this the catalogue is one pane, and the detail is something
+ * you open.
+ */
+export declare const SPLIT_AT: BindingPath;
+export declare const SPLIT_DEFAULT = 140;
+/**
+ * The runtime's own state, read rather than asked for.
+ *
+ * `screens.current()` and `focus.focused()` are method calls: correct at the
+ * moment they run and attached to nothing. A surface that survives navigating -
+ * which is the whole point of a surface - has to subscribe instead, or it
+ * keeps the chrome of the screen you left.
+ */
+export declare const SCREEN: BindingPath;
+export declare const FOCUS: BindingPath;
+export interface HostState {
+    id: string;
+    url: string;
+    state: 'connecting' | 'connected' | 'offline';
+}
+/**
+ * Fold one thing the host said into the store.
+ *
+ * A delta is a word, so this runs per word during a turn. It writes the whole
+ * turn list because the store is addressed by path and a mutation in place is
+ * a change nothing can see - a real client debounces the write, which is a
+ * change here and nowhere above.
+ */
+export declare function applyEvent(store: ReactiveStore, event: HostEvent, model: Turn[]): Turn[];
+/** The answer has gone to the host, which has not said anything about it yet. */
+export declare function sendingInput(store: ReactiveStore, text: string): void;
+/** It is not going, and this is why. */
+export declare function inputRefused(store: ReactiveStore, text: string): void;
+/**
+ * The host refused something, wherever it was asked from.
+ *
+ * The footer says so always. The block waiting on a person says so too when
+ * it was that block's answer being refused, and only then - a refusal earned
+ * by some other command has no business turning the row above the composer
+ * red, which is exactly what reading `HOST_ERROR` from there would do.
+ */
+export declare function reportHostError(store: ReactiveStore, message: string): void;
+/** The number, and the one question everything else asks of it. */
+export declare function writeStatus(store: ReactiveStore, status: number): void;
+export declare function writeSessions(store: ReactiveStore, sessions: SessionSummary[]): void;
+export declare function sessions(store: ReactiveStore): SessionSummary[];
+/**
+ * The catalogue as the list shows it.
+ *
+ * Archived is hidden rather than filtered out of existence: a session somebody
+ * put away is still a session, and the count of what is hidden is what tells
+ * the reader the list is not everything.
+ */
+export declare function visibleSessions(store: ReactiveStore): SessionSummary[];
+/**
+ * How many sessions the archived switch is keeping out of the list.
+ *
+ * Zero while the switch is on, because then it is keeping none out. What it
+ * counts is the difference the switch would make: a row offering to show
+ * archived sessions where there are none to show is a row that does nothing.
+ */
+export declare function hiddenSessions(store: ReactiveStore): number;
+export declare function openSession(store: ReactiveStore): SessionSummary | null;
+export declare function turns(store: ReactiveStore): Turn[];
+export declare function pendingInput(store: ReactiveStore): PendingInput | null;
+export declare function changes(store: ReactiveStore): Changeset;
+/** The running turn, if there is one. Never in the history until it finishes. */
+export declare function activeTurn(store: ReactiveStore): Turn | null;
+export declare function queue(store: ReactiveStore): QueuedMessage[];
+/** A short name for a `file://` working directory. */
+export declare function workspaceName(uri: string | undefined): string;
+/**
+ * What to call the project a session is in.
+ *
+ * The host's own name when it gives one, and the last segment of the working
+ * directory when it does not - which is the same answer for most hosts and the
+ * right one for a host that names projects itself.
+ */
+export declare function projectName(session: SessionSummary): string;
+/**
+ * The branch a session's directory is on, if its host says.
+ *
+ * Two spellings, because there are two vocabularies and only one of them is
+ * written down anywhere. `branchName` is what the reference host sends and is
+ * the one to prefer; `branch` is what one other host sent until it adopted the
+ * reference's names. Neither is in the specification - `git` is a well-known
+ * key in an open map and its contents are convention - so reading only the
+ * name this client happened to meet first is how the branch row came to say
+ * "the host does not say" against a host that was saying it all along.
+ */
+export declare function branchName(session: SessionSummary): string | undefined;
+/**
+ * How far the branch has drifted, where the host counted.
+ *
+ * Ahead, behind and uncommitted, in the arrows a person reads without a
+ * legend. Zeroes are left out rather than drawn as zeroes: the interesting
+ * state is the one that is not clean, and three noughts beside every branch is
+ * three columns of nothing.
+ */
+export declare function branchDrift(session: SessionSummary): string | undefined;