@markmo/europacore-client 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Mark Moloney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The fonts installed through @fontsource-variable/* are each under the SIL Open
+Font License 1.1, which ships with them.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @markmo/europacore-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the europacore server API (`europacore/docs/server-api.md`): its types generated from the server's own OpenAPI document and event schema, the HTTP client, and the resilient SSE reader. No framework and no dependencies; it runs in browsers and in Node 22.
+
+The session UI (`@markmo/europacore-session-ui`) and europacorecli use it, so a change to the server's wire shapes reaches both through one regeneration.
+
+## Use it
+
+```ts
+import { EuropacoreClient, isEvent, pauseOf, type Session } from '@markmo/europacore-client';
+
+const client = new EuropacoreClient({
+  baseUrl: 'https://agents.example.com/v1',
+  headers: async () => ({ Authorization: `Bearer ${await token()}` }),
+});
+
+const session: Session = await client.createSession({ agent: 'coder' });
+await client.createRun(session.id, { input: { text: 'Fix the failing test' } });
+
+const tail = client.subscribeSession(session.id, 0, {
+  onEnvelope: env => {
+    if (isEvent(env, 'tool-call-end')) console.log(env.data.display?.kind); // data typed from the schema
+  },
+});
+
+const question = pauseOf(session.pause, 'question'); // QuestionPause | null
+const recent = await client.runsIndex({ status: 'failed', limit: 20 }); // GET /v1/runs
+const reports = await client.evals(); // GET /v1/evals
+```
+
+`new EuropacoreClient(() => transport)` reads the transport at each call, for an app whose base URL or headers change.
+
+## What is in it
+
+- `src/generated/`: written by `scripts/generate.mjs`, never by hand.
+  - `api.ts`: openapi-typescript's `paths`, `operations` and `components` from `schema/server-openapi.json`. Every field of a response is there: the server writes each one whole, so a value it lacks is `null`.
+  - `events.ts`: json-schema-to-typescript's types for every definition in `schema/server-events.schema.json`, the pauses and tool displays as `kind` unions, plus `EventData` (each event type's `data`, from `x-events`) and `FeedData` (the attention feed's).
+  - `requestOptional.ts`: the fields a request may leave out of each schema it uses, for `RequestBody<'CreateRun'>`.
+- `src/wire.ts` (and `src/wire/`): the types under the names the clients use (`Session`, `Run`, `Pause`, `AgentInfo`, `TranscriptItem`, ...). Most are generated types; where the schema leaves a field open (`Session.pause`, `ServerInfo.capabilities`) they are typed further, and the few shapes not in the schema yet (background and fleet tasks, memories, the transcript) are written out. `src/wire/conformance.ts` checks at compile time that the hand-written ones agree with the generated ones.
+- `src/client.ts` and `src/resources.ts`: `EuropacoreClient`, one method per route. `src/http.ts`: one call with a deadline, retried when it is safe to send again.
+- `src/stream.ts`, `src/sse.ts`, `src/attentionFeed.ts`: the session tail (`openSse`), the SSE parser, and `GET /v1/events`.
+
+## Regenerate the types
+
+The schemas are vendored from a europacore commit, named in `schema/SOURCE`:
+
+1. Copy `docs/server-openapi.json` and `docs/server-events.schema.json` from that europacore commit into `schema/`.
+2. Put the commit, and the date, in `schema/SOURCE`.
+3. Run `npm run generate -w @markmo/europacore-client` (in `frontend/`).
+4. Run `npm run typecheck` and `npm test`: the compiler shows each place a changed shape reaches, here and in the session UI.
+
+`npm test` runs `scripts/generate.mjs --check`, which fails when `src/generated/` is not what the vendored schemas give. The generators are pinned (`openapi-typescript`, `json-schema-to-typescript`), so the output changes only with the schemas or a deliberate upgrade.
+
+The size gate (`frontend/scripts/check_sizes.mjs`) skips `src/generated/`: those files are as long as the schemas they come from, and their source of truth is the generator and its input, which the gate does measure.
+
+## Build and publish
+
+`npm run build -w @markmo/europacore-client` writes `dist/`: one ES module (`index.js`) and its declarations. Inside this repository, the app, the session UI and its tests read the source instead, through the `europacore-source` export condition; the session UI's own declarations read `dist`, so `npm run build:packages` builds this package first.
+
+Pushing a tag `europacore-client-v<version>` publishes it to npm (`.github/workflows/publish-europacore-client.yml`, trusted publishing); the tag must match `version`. A session UI release that needs a new client waits for the client's.
+
+## Use it before it is published
+
+From another checkout, depend on the package by path and build it once:
+
+```sh
+npm --prefix ../europacoreui/frontend ci
+npm --prefix ../europacoreui/frontend run build -w @markmo/europacore-client
+npm install ../europacoreui/frontend/packages/europacore-client
+```
+
+Its relative imports carry `.js` and `dist/` is plain ESM with declarations, so it resolves under `moduleResolution: "nodenext"` as well as `"bundler"`.

package/dist/attentionFeed.d.ts

@@ -0,0 +1,16 @@
+import { type ConnectionState, type SseHandle } from './stream.js';
+import type { Transport } from './transport.js';
+import type { AttentionFrame } from './wire.js';
+export interface AttentionFeedHandlers {
+    onFrame: (frame: AttentionFrame) => void;
+    onState?: (state: ConnectionState, detail?: string) => void;
+    /** Not retryable (a server or proxy without the route, say): the feed is closed. */
+    onFatal?: (error: Error) => void;
+}
+/** A frame's `{v, ts, type, data}` envelope as an AttentionFrame; null for a type this client doesn't know. */
+export declare function attentionFrame(env: {
+    type?: unknown;
+    data?: unknown;
+}): AttentionFrame | null;
+/** Follow `{baseUrl}/events`, reconnecting (for a fresh snapshot) across drops, until closed. */
+export declare function openAttentionFeed(baseUrl: string, transport: Omit<Transport, 'baseUrl'>, handlers: AttentionFeedHandlers): SseHandle;

package/dist/client.d.ts

@@ -0,0 +1,139 @@
+import { type AttentionFeedHandlers } from './attentionFeed.js';
+import { ResourceClient } from './resources.js';
+import { type ConnectionState, type SseHandle } from './stream.js';
+import type { AcceptResult, AddedDir, AgentInfo, BackgroundSubagent, BackgroundTask, ClaimsView, ContextUsage, CreateRun, CreateSession, Envelope, McpServer, ModelInfo, Page, RedoResult, RestoreResult, ResumeRequest, Run, RunInspection, RunSummary, ServerCommand, ServerInfo, Session, SessionPullRequest, SessionSchedule, SessionStatus, SessionTaskEntry, SnapshotInfo, TaskInfo, TranscriptItem, UndoRequest, UndoResult, WorkspaceDiff, WorkspaceInfo } from './wire.js';
+export interface StreamHandlers {
+    onEnvelope: (env: Envelope) => void;
+    onState?: (state: ConnectionState, detail?: string) => void;
+    onFatal?: (error: Error) => void;
+}
+export declare class EuropacoreClient extends ResourceClient {
+    info(): Promise<ServerInfo>;
+    agents(): Promise<AgentInfo[]>;
+    agent(name: string): Promise<AgentInfo>;
+    models(): Promise<{
+        models: ModelInfo[];
+        default: string | null;
+    }>;
+    createSession(body: CreateSession): Promise<Session>;
+    listSessions(query?: {
+        agent?: string;
+        status?: SessionStatus;
+        cursor?: string;
+        limit?: number;
+    }): Promise<Page<Session>>;
+    getSession(id: string): Promise<Session>;
+    updateSession(id: string, patch: {
+        title?: string;
+        model?: string;
+        metadata?: Record<string, unknown>;
+        permission_mode?: string;
+    }): Promise<Session>;
+    deleteSession(id: string): Promise<void>;
+    /** The session's sub-agents delegated in the background. */
+    subagents(id: string): Promise<BackgroundSubagent[]>;
+    /**
+     * The session's background tasks (those running, and those finished since its last turn started), or a fleet
+     * session's run: its tasks, integrator and pull request.
+     */
+    tasks(id: string): Promise<SessionTaskEntry[]>;
+    /** Stop a background task; resolves to it as stopped. */
+    stopTask(id: string, taskId: string): Promise<BackgroundTask>;
+    /** All transcript items, oldest first. Pages run newest first; each page is oldest first. */
+    messages(id: string): Promise<TranscriptItem[]>;
+    /** A copy of the session: its last `keep_groups` turns, or the history before `before_message`. */
+    forkSession(id: string, body?: {
+        keep_groups?: number;
+        before_message?: string;
+        title?: string | null;
+    }): Promise<Session>;
+    /** What fills the session's context window, by category. */
+    context(id: string): Promise<ContextUsage>;
+    /** Summarise the session's older turns now. */
+    compact(id: string, instructions?: string): Promise<Record<string, unknown>>;
+    /** The slash commands the session's agent runs itself. */
+    commands(id: string): Promise<ServerCommand[]>;
+    /** The session's runs from its journal, oldest first. */
+    runs(id: string): Promise<RunSummary[]>;
+    /** One run step by step: tokens, cache and cost per call, tool calls with arguments and results, events. */
+    runSteps(id: string, runId: string): Promise<RunInspection>;
+    /** The session's agent's MCP servers and how each is doing. */
+    mcpServers(id: string): Promise<McpServer[]>;
+    /** The session's cron schedule; null when it has none. */
+    schedule(id: string): Promise<SessionSchedule | null>;
+    /** Set the session's schedule (replacing any); a 422 `invalid_schedule` says what is wrong with it. */
+    setSchedule(id: string, body: {
+        cron: string;
+        prompt: string;
+        timezone?: string;
+    }): Promise<SessionSchedule>;
+    /** Clear the session's schedule. */
+    clearSchedule(id: string): Promise<void>;
+    /** Connect an enabled MCP server again, after it failed or its process died. */
+    reconnectMcp(id: string, name: string): Promise<{
+        server: string;
+        tools: string[];
+    }>;
+    /** The session's file claims, the other sessions in its repository with theirs, and requests to or from it. */
+    claims(id: string): Promise<ClaimsView>;
+    /**
+     * Let go of one of your own sessions' claims (every one without `paths`), or with `to` hand them to another
+     * session. What follows arrives as `claim.resolved` and in the sessions' `metadata.claims`.
+     */
+    releaseClaims(id: string, body: {
+        paths?: string[];
+        to?: string;
+        note?: string;
+    }): Promise<ClaimsView>;
+    /** Ask, on behalf of your own session, for paths another session holds; the request arrives as `claim.requested`. */
+    requestClaims(id: string, body: {
+        paths: string[];
+        reason?: string;
+    }): Promise<ClaimsView>;
+    /** The session's workspace: branch and the files changed since `base` (HEAD by default). */
+    sessionWorkspace(sessionId: string, base?: string): Promise<WorkspaceInfo>;
+    /** A unified diff of the session's workspace; one file when `path` (repository-relative) is given. */
+    workspaceDiff(sessionId: string, options?: {
+        path?: string;
+        base?: string;
+        task?: string;
+    }): Promise<WorkspaceDiff>;
+    /** Task worktrees started from the session's branch (its delegated coders). */
+    sessionTasks(sessionId: string): Promise<TaskInfo[]>;
+    /** Fast-forward the session worktree's base branch to it; `message` commits leftovers first. */
+    acceptWorkspace(sessionId: string, message?: string): Promise<AcceptResult>;
+    /** Remove the session's worktree and branch; `force` discards unmerged work. */
+    discardWorkspace(sessionId: string, force?: boolean): Promise<void>;
+    /** The session's workspace snapshots, oldest first: one per turn, and one before each restore. */
+    listSnapshots(sessionId: string): Promise<SnapshotInfo[]>;
+    /** Put the workspace's files (those under `paths`, or all) back as snapshot `id` has them. */
+    restoreSnapshot(sessionId: string, id: number, paths?: string[]): Promise<RestoreResult>;
+    /** Undo the session's last turn (or `turns`, back to before `to`, or `all`): the conversation and its files. */
+    undo(sessionId: string, body?: UndoRequest): Promise<UndoResult>;
+    /** Put back what the newest undo since the session's last turn took away. */
+    redo(sessionId: string): Promise<RedoResult>;
+    /** Let the session's agent use `path` (under the user's workspace root) too; `writable` lets it write there. */
+    addDir(sessionId: string, path: string, writable?: boolean): Promise<AddedDir[]>;
+    /** Stop the session's agent using an added directory. */
+    removeDir(sessionId: string, path: string): Promise<AddedDir[]>;
+    /** The pull requests a session opened or registered. */
+    pullRequests(sessionId: string): Promise<SessionPullRequest[]>;
+    /** Register a pull request the session works on (one opened elsewhere), following its CI and reviews. */
+    addPullRequest(sessionId: string, ref: {
+        url?: string;
+        number?: number;
+    }): Promise<SessionPullRequest>;
+    /** Follow a session's pull request's CI and reviews, or stop. */
+    followPullRequest(sessionId: string, number: number, follow: boolean): Promise<SessionPullRequest>;
+    createRun(sessionId: string, body: CreateRun): Promise<Run>;
+    resume(sessionId: string, body: ResumeRequest): Promise<Run>;
+    getRun(runId: string): Promise<Run>;
+    cancelRun(runId: string, reason?: string): Promise<Run>;
+    steer(runId: string, text: string, commandId?: string): Promise<{
+        delivered: boolean;
+    }>;
+    /** Session tail: replays after `after` (omit for live-only), then follows every run. */
+    subscribeSession(sessionId: string, after: number | string | undefined, handlers: StreamHandlers): SseHandle;
+    /** The attention feed (`capabilities.attention_feed`): a snapshot of the caller's sessions, then each change. */
+    subscribeAttention(handlers: AttentionFeedHandlers): SseHandle;
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import type { Problem } from './wire.js';
+/** An HTTP failure from the server, carrying the RFC 9457 problem body when there is one. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly problem: Problem;
+    constructor(problem: Problem);
+}
+/** The server didn't answer a request in time: hung, or too busy to. */
+export declare class RequestTimeoutError extends Error {
+    constructor(method: string, path: string, timeoutMs: number);
+}
+export declare function problemFromResponse(res: Response): Promise<ApiError>;
+export declare function describeError(error: unknown): string;