@ahpd/server 0.1.0 → 0.2.0

package/src/types/automations.ts

@@ -1,164 +0,0 @@
-/** Automations: a session started by a trigger rather than by a person. */
-
-import type { AutomationOperation, SessionOriginKind } from '@microsoft/agent-host-protocol';
-
-import type { Bag } from './common.js';
-
-/**
- * One automation, as the catalogue channel carries it.
- *
- * The definition is the client's - it wrote it and can patch it - and
- * everything around it is the store's: when it will next fire, what it has
- * done, and which of the three verbs may be used on it now.
- */
-export interface Automation {
-  /** `ahp-automation:/<id>`. The channel a run is reported against names it. */
-  resource: string;
-  /** What the client asked for. Opaque here except for `enabled` and `title`. */
-  definition: Bag;
-  /** ISO 8601, when a schedule says it will fire next. Absent for one nothing will fire. */
-  nextRunAt?: string;
-  /** Newest first. A summary per run, not the runs themselves. */
-  runs: Bag[];
-  /** More runs than were sent, if there are. */
-  runsNextCursor?: string;
-  /** Which of `update`, `remove`, `run` this store will accept for it now. */
-  operations: `${AutomationOperation}`[];
-  createdAt: string;
-  modifiedAt: string;
-}
-
-/** One run of one automation. */
-export interface AutomationRun {
-  /** `ahp-automation-run:/<id>`, which is also a channel a client may watch. */
-  resource: string;
-  /** The automation it is a run of. */
-  automation: string;
-  /** Why it started: somebody pressed it, or a trigger fired. */
-  origin: Bag;
-  /** `pending`, `running`, `completed`, `failed`, `cancelled`, and when each happened. */
-  lifecycle: Bag;
-  /** The sessions it started. Usually one. */
-  sessions: string[];
-  /** The one a client should open when it opens the run. */
-  primarySession?: string;
-}
-
-/** How a store asks the host to start a session, since only the host can. */
-export interface StartSession {
-  /** The provider named in the automation's session template, or the default. */
-  provider?: string;
-  /** Where it should work. */
-  workingDirectory?: string;
-  /** Config values for the new session. */
-  config?: Record<string, unknown>;
-  /** The first message, which is what the automation is *for*. */
-  text: string;
-  /**
-   * The run this session will belong to.
-   *
-   * Passed down rather than looked up, because it becomes the session's own
-   * `origin` and a catalogue is where it is read: a session that started at
-   * nine with nobody at the keyboard is otherwise a row with no account of
-   * itself, sitting among rows somebody typed.
-   */
-  origin?: { kind: `${SessionOriginKind}`; automation: string; run: string };
-}
-
-/**
- * Where a host's automations come from.
- *
- * A port, like the filesystem and the shell, and for a reason of its own: an
- * automation that fires on a schedule needs something holding a clock, and a
- * host embedded in an editor already has one while a daemon on a box may
- * deliberately have none. A host given no store advertises no automations
- * channel and answers `-32601` for all three commands - which is a true answer
- * rather than an empty screen.
- *
- * Deciding it is time is the store's business. `run` is called when a person
- * presses Run or when a store holding a clock says one is due through
- * `onDue` - so what a schedule means, and when it comes round, is behind this
- * interface and not in front of it.
- */
-export interface AutomationStore {
-  /** Every automation, for the catalogue channel's snapshot. */
-  list(): Automation[];
-  /** One, by resource URI. Undefined for one this store has never heard of. */
-  get(resource: string): Automation | undefined;
-
-  /**
-   * The *event* triggers this store understands.
-   *
-   * Only event triggers: a schedule trigger is protocol-defined, is never
-   * listed here, and may always be written - what a client learns from a host
-   * that will not fire one is the absent `nextRunAt`, not an absence here.
-   * Manual is not a trigger either; an empty trigger list on a definition is
-   * what manual-only means. So empty is a real answer, and the usual one.
-   */
-  triggers(options: { provider?: string; workingDirectories?: string[] }): Bag[];
-
-  /** Write one the client has just described. */
-  create(resource: string, definition: Bag): Automation;
-  /** Patch one. Absent keys are left alone, which is what a patch means. */
-  update(resource: string, changes: Bag): Automation | undefined;
-  /** Forget one, and everything it ever did. */
-  remove(resource: string): boolean;
-
-  /**
-   * Start a run.
-   *
-   * `start` is handed in rather than reached for: only the host can create a
-   * session, and a store that could would be a second thing that knows what a
-   * session is. It answers the session URI, and the store records it.
-   */
-  run(
-    resource: string,
-    origin: Bag,
-    start: (options: StartSession) => Promise<string>,
-  ): Promise<AutomationRun | undefined>;
-
-  /** One run's own state, for the channel a client watches it on. */
-  runOf(resource: string): AutomationRun | undefined;
-  /** A page of an automation's runs, newest first. */
-  runs(resource: string, cursor?: string): { items: Bag[]; nextCursor?: string };
-
-  /**
-   * Let go of a session a run was holding.
-   *
-   * Called when the session is disposed: a run keeps a list of URIs and a
-   * host that removed the session without saying so would leave a run
-   * pointing at a channel nobody can open. Removing the primary clears it,
-   * which is what the protocol says. Answers whether the set actually moved,
-   * so a URI a run never had is a no-op rather than an announcement.
-   *
-   * Optional, like everything else a store may not do: a store that keeps its
-   * runs immutable simply leaves it out.
-   */
-  unlink?(run: string, session: string): boolean;
-
-  /**
-   * Called when something in here moved, so the host can say so.
-   *
-   * The store owns the clock and the host owns the channels, so this is the
-   * only way an automation that fired on its own reaches anybody.
-   */
-  onChanged?(observer: (event: { automation?: string; run?: string; removed?: string }) => void): void;
-
-  /**
-   * Called when this store's clock says one is due.
-   *
-   * The counterpart of `run`, and the reason that method takes `start` rather
-   * than holding it: a store that fires on its own still cannot create a
-   * session, so it says *which* automation is due and with what origin, and
-   * the host - the only thing that knows what a session is - calls `run`. A
-   * store with no clock never calls this, and a host that never wired it is a
-   * host where nothing fires by itself.
-   *
-   * The origin is the store's because only it knows which trigger came round,
-   * which occurrence it was, and whether it is catching one up.
-   */
-  onDue?(observer: (event: { automation: string; origin: Bag }) => void): void;
-
-  /** Let go of the clock, so a daemon shutting down is not held open by one. */
-  close?(): void;
-}

package/src/types/catalog.ts

@@ -1,26 +0,0 @@
-/** The session catalogue, as the root channel reports it. */
-
-/** One row of the session list. */
-export interface Summary {
-  /** The session's channel URI, `ahp-session:/<id>`. */
-  resource: string;
-  /** The agent backend that runs it. Always `claude` here. */
-  provider: string;
-  /** Display title: the host's own summary, or the first prompt. */
-  title: string;
-  /** `SessionStatus` bitset - activity in the low bits, client flags above. */
-  status: number;
-  /** ISO 8601 timestamp of creation. */
-  createdAt: string;
-  /** ISO 8601 timestamp of the last change. */
-  modifiedAt: string;
-  /** Directories the agent has tool access to, as `file://` URIs. */
-  workingDirectories: string[];
-  /**
-   * What started it, when it was not a person.
-   *
-   * Absent for a session somebody opened, which is what the protocol says
-   * absent means. Only automations set it.
-   */
-  origin?: { kind: 'automation'; automation: string; run: string };
-}

package/src/types/changes.ts

@@ -1,266 +0,0 @@
-/** What a session changed, as the protocol's changeset channel carries it. */
-
-import type {
-  ChangesetOperationScope as Scope,
-  ChangesetOperationTargetKind as TargetKind,
-  ChangesetStatus,
-} from '@microsoft/agent-host-protocol';
-
-/** A pointer to content the state tree does not carry. */
-export interface ContentRef {
-  uri: string;
-  sizeHint?: number;
-  contentType?: string;
-}
-
-/**
- * One file, on both sides of the change.
- *
- * `before` absent is a creation and `after` absent a deletion, which is how
- * the protocol says both rather than carrying a status word for them.
- */
-export interface FileEdit {
-  before?: { uri: string; content: ContentRef };
-  after?: { uri: string; content: ContentRef };
-  diff?: { added?: number; removed?: number };
-}
-
-/** One row of a changeset. `id` is stable within it. */
-export interface ChangesetFile {
-  id: string;
-  edit: FileEdit;
-  reviewed?: boolean;
-}
-
-/** What a client subscribed to a changeset URI is looking at. */
-export interface ChangesetState {
-  /**
-   * Where the computation is, in the protocol's own three words.
-   *
-   * Taken from `ChangesetStatus` rather than written out. This port said
-   * `computing | complete | error` for the life of the project and the
-   * protocol says `computing | ready | error`, so every changeset ever served
-   * carried a status word no client could recognise - and nothing caught it,
-   * because a hand-copied union is checked against nothing.
-   */
-  status: `${ChangesetStatus}`;
-  files: ChangesetFile[];
-}
-
-/** The roll-up a catalogue row carries, so a list needs no subscription. */
-export interface ChangesSummary {
-  files?: number;
-  additions?: number;
-  deletions?: number;
-}
-
-/**
- * One scope of change a directory can be asked about.
- *
- * The protocol nests changesets under the session's own URI - `uncommitted`,
- * `session`, `turn/<id>` - so a scope is the last part and the host composes
- * the rest. Keeping it that way round means a source never has to know what a
- * session is called.
- */
-export interface ChangesetScope {
-  /** The path segment, e.g. `uncommitted`. */
-  id: string;
-  /** What a client shows, e.g. `Uncommitted Changes`. */
-  label: string;
-  description?: string;
-  /**
-   * What kind of changeset this is, so a client can group and sort without
-   * parsing the URI. The protocol names `session`, `branch`, `uncommitted`,
-   * `turn` and `compare-turns`, and says a client should fall back sensibly
-   * on one it does not know.
-   */
-  changeKind: string;
-  /**
-   * Whether files in this changeset can be marked reviewed.
-   *
-   * A presence flag on the catalogue entry, which is what lets a client decide
-   * whether to draw the checkbox *before* it subscribes to anything. Review is
-   * not an operation: the client dispatches `changeset/filesReviewChanged` and
-   * the server keeps the flag.
-   */
-  reviewable?: boolean;
-}
-
-/**
- * Where an operation may be invoked.
- *
- * The protocol's three: the whole changeset, one file in it, or a line range
- * within one file. A source declares which it accepts and the host refuses an
- * invocation whose target is not among them.
- */
-export type ChangesetOperationScope = `${Scope}`;
-
-/** The file, or the lines of it, an operation was pointed at. */
-export interface ChangesetOperationTarget {
-  kind: `${TargetKind}`;
-  /** The `ChangesetFile.id` of the row, which is a `file://` URI. */
-  resource: string;
-  /** Which side of the edit, where an operation can act on either. */
-  side?: 'before' | 'after';
-  /** Present iff `kind` is `range`. Lines are 1-based, as the protocol has them. */
-  range?: { startLine: number; startColumn?: number; endLine: number; endColumn?: number };
-}
-
-/**
- * A verb a client may run against a changeset.
- *
- * Server-advertised, and that is the whole access model: `invokeChangesetOperation`
- * carries an `operationId` that must match one this source already offered for
- * this scope, so a client can ask for nothing that was not put in front of it.
- *
- * There is no `status` here because status is not the source's. Whether an
- * operation is disabled depends on whether the session is mid-turn, and whether
- * it is running depends on an invocation in flight - both of which the host
- * knows and a source does not.
- */
-export interface ChangesetOperation {
-  /** Stable within the changeset, and what an invocation names. */
-  id: string;
-  /** The button. */
-  label: string;
-  /** Longer text, for a tooltip. */
-  description?: string;
-  /** The targets this operation accepts. */
-  scopes: ChangesetOperationScope[];
-  /**
-   * The question to ask before running it.
-   *
-   * Its presence is also how the protocol says "this is destructive": a client
-   * MUST show it, and SHOULD style the affirmative button as a warning.
-   */
-  confirmation?: string;
-  /** A hint, e.g. `git-commit` or `discard`. */
-  icon?: string;
-  /** Operations sharing one are drawn together. */
-  group?: string;
-  /**
-   * Whether running it writes to the working tree.
-   *
-   * What the host gates on: an operation that writes needs a write grant on the
-   * resource, negotiated through `resourceRequest`, and is refused with `-32009`
-   * until one is held. Declared here rather than inferred from the id, because
-   * the host cannot know what a source's verbs do.
-   */
-  writes?: boolean;
-}
-
-/** One invocation, as the host hands it to the source. */
-export interface ChangesetOperationRequest {
-  dir: string;
-  session: string;
-  /** The scope segment, e.g. `uncommitted` or `turn/abc`. */
-  scope: string;
-  operationId: string;
-  /** Absent for a changeset-scoped operation. */
-  target?: ChangesetOperationTarget;
-  /**
-   * What the session is called, offered as a commit subject.
-   *
-   * The host's to know and not this source's: a changeset is a set of files and
-   * a session is a conversation, and the sentence somebody would write on a
-   * commit is in the second one.
-   */
-  subject?: string;
-}
-
-/** What an invocation says for itself. Thrown errors are the failure path. */
-export interface ChangesetOperationResult {
-  /** One line for the client to show. */
-  message?: string;
-  /**
-   * Something to open afterwards, when the operation produced one.
-   *
-   * A `ContentRef` - a URI, a size hint, a content type - and whether the
-   * client should open it in a browser rather than inline. A pull request a
-   * commit-and-push produced is the case this exists for: the operation
-   * succeeded, and the useful thing about it is a page somewhere.
-   */
-  followUp?: {
-    content: { uri: string; sizeHint?: number; contentType?: string; nonce?: string };
-    external?: boolean;
-  };
-}
-
-/**
- * Where a host's file changes come from.
- *
- * A port, like the filesystem and the shell, and for the sharpest version of
- * the same reason: a diff comes from `git`, which is a binary that may not be
- * installed, against a directory that may not be a repository. A host given
- * none advertises no changesets, which is a true answer rather than an empty
- * screen.
- */
-export interface ChangesetSource {
-  /**
-   * Which scopes can be answered here. Empty for a directory that has none.
-   *
-   * `session` is passed because two of the protocol's scopes are a session's
-   * rather than a directory's - what *this conversation* changed is not what
-   * the working tree looks like, and a directory with three sessions in it has
-   * three different answers.
-   */
-  scopes(dir: string, session: string): ChangesetScope[];
-  /** The state behind one of them. */
-  state(dir: string, session: string, scope: string): Promise<ChangesetState | undefined>;
-  /** The roll-up for a catalogue row, cheap enough to ask per row. */
-  summary(dir: string): ChangesSummary | undefined;
-  /**
-   * Content behind a ref this source minted.
-   *
-   * The `before` side of an edit is not a file on disk - it is what the file
-   * used to be - so it cannot be served by the filesystem port. Undefined for
-   * a URI this source does not own, which is how the host knows to try the
-   * filesystem instead.
-   */
-  read?(uri: string): Promise<{ data: string; encoding: string } | undefined>;
-  /** Look again, answering whether anything moved. */
-  refresh?(dir: string): Promise<boolean>;
-  /**
-   * Mark files reviewed, or clear them.
-   *
-   * A person's bookkeeping about a diff they are reading, not a change to
-   * anything on disk - which is why it is the one thing here a client may
-   * write. Answers whether anything moved, so an idempotent toggle tells
-   * nobody about a state it already had.
-   */
-  review?(dir: string, session: string, scope: string, files: string[], reviewed: boolean): boolean;
-  /**
-   * A file an agent is about to change, and the same file once it has.
-   *
-   * What makes a *turn's* changeset the turn's. Git can only ever say what a
-   * working tree looks like now, so a turn asked about later would be handed
-   * every turn after it as well; capturing both sides as the tool runs is the
-   * only way the answer stays the turn's own.
-   *
-   * Reading the file is this source's business - it is the thing here that
-   * has a filesystem - and the session only says which one and when.
-   */
-  observe?(dir: string, session: string, turnId: string, path: string, phase: 'before' | 'after'): void;
-  /**
-   * The verbs this source offers on one scope, in the order to draw them.
-   *
-   * Asked per scope because the answer differs by scope: the working tree can
-   * be committed and a turn cannot, and what a turn changed can be put back
-   * because both sides of every file in it were captured.
-   *
-   * Empty is a real answer and the one to give for a scope with nothing to do
-   * to it. A source with no method at all advertises none anywhere, which is
-   * what a host serving a directory it may not write looks like.
-   */
-  operations?(dir: string, session: string, scope: string): ChangesetOperation[];
-  /**
-   * Run one.
-   *
-   * The host has already checked that `operationId` is among what this source
-   * offered for this scope, that the target's kind is one the operation
-   * accepts, and that a write grant is held where the operation says it writes.
-   * What is left is doing it, and throwing if it did not work - the protocol
-   * signals failure by rejecting the request, not by a field on the result.
-   */
-  invoke?(request: ChangesetOperationRequest): Promise<ChangesetOperationResult>;
-}

package/src/types/common.ts

@@ -1,9 +0,0 @@
-/** Shapes shared by more than one channel. */
-
-/**
- * An object with no declared shape.
- *
- * Used for JSON arriving off the wire and for the agent SDK's frames, both of
- * which are read field by field rather than trusted as a type.
- */
-export type Bag = Record<string, unknown>;