framework
Version:
The (AI) Framework: turnkey, zero-config AI orchestration that wraps a coding-agent CLI (Claude Code) as a black box and takes you from an idea to a running app. Vite for AI.
207 lines • 13.6 kB
TypeScript
import { type AgentMeta } from '../store/index.js';
import { type WorkspaceDoc } from '../dashboard/docs.js';
import { type WorkspaceTicket, type WorkspaceTicketDetail, type TicketsMeta } from '../dashboard/tickets.js';
import { type ProjectQueue } from '../dashboard/queue.js';
import { type Overview, type RecentAgent, type HotTicket, type ProjectTickets } from '../dashboard/overview.js';
import { type Intervention } from '../dashboard/interventions.js';
import type { ProjectionRead } from '../dashboard/projects.js';
import { type OpenQuestion } from '../dashboard/open-questions.js';
import { type Activity } from '../dashboard/activity.js';
import { type DashboardData } from '../dashboard/dashboard.js';
import { type GitStatus } from '../dashboard/git-status.js';
import { type AgentHandoff } from '../dashboard/agent-handoff.js';
import type { AgentWorktree } from '../dashboard/types.js';
import { type FileGitStatus } from '../dashboard/file-status.js';
import { type FileDiff, type FileChange } from '../dashboard/file-diff.js';
import { type FileContent } from '../dashboard/file-read.js';
import type { FrameworkEvent } from '../events.js';
import type { BridgeEvent, BridgeHello, BridgeQuestion } from '../dashboard/bridge-endpoints.js';
import type { BridgeAnswer, BridgeContact, BridgeVersion } from '../dashboard/bridge-store.js';
/**
* The project's runs, most-recent first (or `[]`). The archived (finished) runs
* from `agents/`, plus every live agent prepended — so the sidebar shows an in-progress
* run with a `running` status the moment it starts, not only after it closes.
*
* Since #736 a project has any number of live agents, each in its own worktree, so this reads
* them all (#738) instead of the single one that used to sit at the project path. They come
* back as {@link LiveAgent}s, carrying the `cwd` of the checkout that agent is editing.
*
* One row per id, and where both a live and an archived copy exist the live one wins (#768): a
* continued run (#762) has an archive from its first leg while being live again, and the archive
* would otherwise show a running agent as finished. The status is not filtered on: `readLiveMeta`
* may have just self-healed a dead agent to `stopped` (#716), and that freshly-archived row can
* lag `listAgents` by a poll — keeping it regardless leaves the row visible with no flicker.
*
* An agent relayed to a connected device (#1067) lives only in the daemon's memory, never on disk, so
* its in-memory stub is merged in too (#1077): that is what re-opens it after a dashboard reload
* instead of losing it.
*/
export declare function onAgents(projectId: string): Promise<AgentMeta[]>;
/**
* The agent ids that still have a worktree on disk (#737). An agent that failed or was stopped keeps
* its checkout so you can go look at what it was holding; this is how the dashboard knows which
* finished run has one to offer removing. Live agents are excluded — their worktree is in use.
*/
export declare function onRetainedWorktrees(projectId: string): Promise<string[]>;
/**
* Where a session is working (#798): the checkout it has, its branch, whether it is holding
* uncommitted changes, and — once it is no longer live — what that checkout costs on disk.
*
* The dashboard could not answer "where is this session working". The git status bar reads the
* *project*, so a session's own branch was visible nowhere, and a worktree an agent kept (#737) was
* a name in a list with no size and no way in.
*
* `own` separates an agent with its own worktree from one that fell back to the main checkout (a
* project with no git repo): "uncommitted changes" means something different there, since that
* working tree is the user's, not the agent's.
*/
export declare function onAgentWorktree(projectId: string, agentId: string): Promise<AgentWorktree | null>;
/** One archived agent's event log for replay (or `[]` when the agent or project is gone). */
export declare function onAgent(projectId: string, agentId: string): Promise<FrameworkEvent[]>;
/** The surfaced PLAN/TODO docs at the workspace root, in sidebar order (or `[]`). */
export declare function onDocs(projectId: string): Promise<WorkspaceDoc[]>;
/** The project's `tickets/*.md`, by filename (#697). `[]` when the repo has no `tickets/` yet. */
export declare function onTickets(projectId: string): Promise<WorkspaceTicket[]>;
/** One ticket's full text, for its own detail page (#1144). Null when it does not exist. */
export declare function onTicket(projectId: string, file: string): Promise<WorkspaceTicketDetail | null>;
/** When `tickets/` last caught up with GitHub (#1208), or `{}` when nothing has recorded it. */
export declare function onTicketsMeta(projectId: string): Promise<TicketsMeta>;
/** Every registered project's tickets, one list per project (#1144): the cross-project Tickets page. */
export declare function onAllTickets(): Promise<ProjectTickets[]>;
/** The aggregated open TODO queue across every registered project (#438), most-open first. */
export declare function onQueue(): Promise<ProjectQueue[]>;
/** The cross-project Overview (#437): what is running now, the queue size, and recent projects. */
export declare function onOverview(): Promise<Overview>;
/** Recent sessions pooled across every project (#shared-shell), newest first, for the home rail. */
export declare function onRecentAgents(): Promise<RecentAgent[]>;
/** Hot tickets across every project (#1112): being worked on, likely next, and queued. */
export declare function onHotTickets(): Promise<HotTicket[]>;
/**
* The cross-project interventions queue (#632, Queue #624): open PRs that need review, newest first,
* plus which projects were read whole (#1625).
*
* The panels render `items` and ignore the rest. The browser's notifier is the caller that cannot:
* it keeps a baseline of what was already waiting when the page opened, and a queue that came back
* empty because GitHub was unreachable is not a baseline — taking it for one announces the whole
* backlog the moment GitHub answers.
*/
export declare function onInterventions(): Promise<ProjectionRead<Intervention>>;
/** Every session's open question with its full gate (#1455), longest-waiting first: the launcher's hub. */
export declare function onOpenQuestions(): Promise<OpenQuestion[]>;
/**
* The cross-project "New activity" feed (#627): recent run started/finished transitions, newest
* first, with the projects that were read whole beside them (#1625) — see {@link onInterventions}.
*/
export declare function onActivity(): Promise<ProjectionRead<Activity>>;
/** The Overview dashboard page (#471): the {@link onOverview} rollup plus agent counts, run-status totals, and activity. */
export declare function onDashboard(): Promise<DashboardData>;
/**
* The project's files for the `#` context picker (#504) and the panel tree (#492): every
* file git sees (tracked + untracked, honoring .gitignore), repo-relative and sorted, via
* `git ls-files`. Localhost-only by nature — the relay has no checkout, so it resolves `[]`.
* Pass a live `agentId` to list that agent's worktree instead of the project root (#738).
*/
export declare function onProjectFiles(projectId: string, agentId?: string): Promise<string[]>;
/**
* Per-file git status for the tree's dots (#492): repo-relative path -> untracked/modified/
* deleted, from `git status --porcelain`. `{}` when not a repo / on the relay (no checkout).
* Pass a live `agentId` to see that agent's own worktree rather than the project root (#738).
*/
export declare function onProjectFileStatus(projectId: string, agentId?: string): Promise<Record<string, FileGitStatus>>;
/**
* One changed file's diff, for the tree's hover card (#816). Null when the path is not a changed
* file, is unsafe (see `safeRepoPath`), or there is no checkout. Reads the agent's own worktree when
* `agentId` names one, so it shows the same change the tree dotted (#815).
*
* The status comes from the same `git status` the dots do, rather than from the caller: a client
* that thinks a file is untracked must not be able to make the server read it as one.
*/
export declare function onFileDiff(projectId: string, path: string, agentId?: string): Promise<FileDiff | null>;
/**
* What the session changed (#817): every changed file in its worktree with line counts, newest
* state each poll. `[]` when nothing changed or there is no checkout.
*
* Derived from the worktree rather than from the agent's tool calls on purpose. The driver
* surfaces a tool's name and not its arguments (#165) — we verify by outcome, not by watching
* which tool the agent reached for — so reading git is both the honest source and the one that
* works for every agent, not just the ones whose stream carries an edit payload.
*/
export declare function onAgentChanges(projectId: string, agentId?: string): Promise<FileChange[]>;
/**
* One unchanged file's contents, for the tree's hover card (#828). Null when the path is unsafe
* (see `safeRepoPath`), outside the checkout, or unreadable. Reads the agent's own worktree when
* `agentId` names one, so it shows the copy the tree is listing (#815).
*
* The caller picks this or {@link onFileDiff} from the status the tree already holds; a changed
* file has a diff worth seeing, an unchanged one has only itself.
*/
export declare function onFileContent(projectId: string, path: string, agentId?: string): Promise<FileContent | null>;
/** The project's GitHub URL from its `origin` remote (#489), or null (no remote / not GitHub / relay). */
export declare function onGithubUrl(projectId: string): Promise<string | null>;
/**
* The project's git status (#491): active branch, dirty flag, linked PR. Null when not a repo /
* relay. Pass a live `agentId` to read that agent's worktree, which is the branch and the dirty
* state that actually belong to it (#738). A run-scoped read is since-filtered (#1255): an agent on
* a reused pinned branch must not wear a predecessor's merged PR as its own badge.
*/
export declare function onGitStatus(projectId: string, agentId?: string): Promise<GitStatus | null>;
/**
* The end-of-session handoff (#799): the branch a finished session left its work on, what it
* committed, what it changed, and whether that has been pushed or opened as a PR.
*
* Read from the *project* checkout against the session's branch, not from the session's worktree.
* A clean agent's worktree is removed when it finishes, and `resolveAgentPath` then falls back to the
* project root — so a worktree-addressed read reports the project's own branch and the user's own
* uncommitted changes as though they were the session's. The branch is what outlives the agent, so
* the branch is what this asks about.
*/
export declare function onAgentHandoff(projectId: string, agentId: string): Promise<AgentHandoff | null>;
/**
* The project's own `SYSTEM.md` text, or null when it has none (#872). The prompt preview
* claims to show the entire system prompt; composition takes this text as `opts.user`, but
* reading it is Node-bound, so the browser needs this read to keep that claim true.
*/
export declare function onSystemPromptUser(projectId: string): Promise<string | null>;
/**
* The question a Claude web session is parked on, as reported by the browser bridge (#1237).
*
* Keyed by cloud session id rather than agent id because that is what the bridge can see: it reads
* a claude.ai page, which knows its session and nothing about our runs. The agent view already
* derives that id from the agent's own `cloud <url>` event, so the join happens on the client
* without the daemon having to index runs by session.
*
* Returns null for anything unrecognised, so an agent with no bridge, no question, or a target that
* is not `web` renders exactly as it did before.
*/
export declare function onBridgeQuestion(sessionId: string): Promise<BridgeQuestion | null>;
/**
* Whether anything has reached the browser bridge, and how it went (#1237).
*
* A misconfigured extension and an uninstalled one both leave no question behind, so "nothing is
* showing" cannot be diagnosed from the questions alone. A refused request at least proves
* something is trying, and its status says which half is wrong.
*/
export declare function onBridgeStatus(): Promise<{
lastContact: BridgeContact | null;
questions: number;
page: BridgeHello | null;
version: BridgeVersion | null;
}>;
/**
* The bridge token, for the setup step where a user pastes it into the extension (#1237).
*
* Only while the bridge is on, so a daemon with the feature off never hands the secret to a
* page. Revealing it here is not a new exposure: anyone who can load this dashboard can already
* start runs on this machine, and on a non-loopback bind their browser is holding the same token
* as a cookie. What it replaces is the alternative, which was telling people to open
* `~/.the-framework.json` and copy a field out of it.
*/
export declare function onBridgeToken(): Promise<string | null>;
/**
* Where the answer picked for that session's question stands (#1237): queued for the
* extension, delivered, or failed with the extension's reason. Null when nothing was picked.
*/
export declare function onBridgeAnswer(sessionId: string): Promise<BridgeAnswer | null>;
/** What a Claude web session has said so far, as scraped by the browser bridge (#1237). */
export declare function onBridgeEvents(sessionId: string): Promise<BridgeEvent[]>;
//# sourceMappingURL=reads.d.ts.map