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.
176 lines • 11.3 kB
TypeScript
import { type OpenTarget, type OpenResult } from '../dashboard/open-in-app.js';
import { type HandoffResult } from '../dashboard/run-handoff.js';
import type { ChoiceBy } from '../events.js';
import type { DeleteSessionResult, PreviewResult, PreviewStatus, RemoveWorktreeResult, StartRunKind, StartRunOptions, StartRunResult } from '../dashboard/types.js';
import type { ServeTarget } from '../preview.js';
/** Stop a live run (the Stop button): append a stop entry to the run's control log. */
export declare function sendStop(projectId: string, runId?: string): Promise<void>;
/**
* Arm or disarm a live session's end-of-session handoff (#1102): whether it pushes its branch and
* opens a draft PR when it finishes.
*
* Steering rather than a setting write, because it is about *this* session: the preference sets
* where the boxes start, and this is the user changing their mind for one run. The run echoes what
* it applied back as an event, so the boxes read from the run's meta rather than from local state
* that a reload would lose.
*/
export declare function sendSetHandoff(projectId: string, runId: string, push: boolean, pr: boolean): Promise<void>;
/**
* Resolve the project's parked choice gate (#304/#332): `pick` is one option id for a
* single-select, or the selected subset for a multi-select. `by` records who picked
* (a human here, vs the autopilot countdown or a headless auto-accept).
*/
export declare function sendChoice(projectId: string, id: string, pick: string | string[], by?: ChoiceBy, runId?: string): Promise<void>;
/**
* Queue the user's pick for the question a Claude web session is parked on (#1237).
*
* Not a control-log write like {@link sendChoice}: a cloud run has no live local session to
* steer, so the pick goes to the bridge store, where the browser extension collects it, types
* it into the session's composer and submits. Only a label of the currently parked question is
* accepted, so this can never put arbitrary text in front of another product's agent. Local
* only, no relay: the bridge lives on the daemon the extension talks to.
*/
export declare function sendBridgeAnswer(sessionId: string, label: string): Promise<{
ok: boolean;
error?: string;
}>;
/** Withdraw a queued bridge answer (#1237). A no-op once the extension has delivered it. */
export declare function sendBridgeAnswerCancel(sessionId: string): Promise<void>;
/**
* Send a live-chat message to the project's running run (#714): append a `message` entry
* that the run drains between turns, continuing the same session via `--resume`. Empty
* messages are dropped.
*
* `via` names the surface the message came through (#917), so the run records the turn where it
* actually happened. The dashboard omits it and keeps its own default; the Discord bot passes
* `discord`. An unsafe name is dropped rather than forwarded: it would reach a line-parsed
* conversation heading, and the browser can call this, so it is not trusted input.
*/
export declare function sendMessage(projectId: string, text: string, runId?: string, via?: string): Promise<void>;
/**
* Remove a retained worktree (#737). A run that failed or was stopped keeps its checkout so you
* can inspect it; this is the explicit cleanup for one, since nothing removes them on a timer.
*
* The checks and the commit-first removal are {@link removeProjectWorktree}'s, shared with the
* `framework worktrees rm` verb (#982) so the two surfaces cannot drift again. All this adds is
* the daemon-only step: a retained worktree can still be serving (#797), and that dev server
* holds the tree being removed, so it is stopped rather than having the directory pulled out
* from under it.
*/
export declare function sendRemoveWorktree(projectId: string, runId: string): Promise<RemoveWorktreeResult>;
/**
* Delete a session (#1032): remove it from the dashboard, records and all — the sibling of
* {@link sendRemoveWorktree}, and the one destructive-of-history action, so its surface confirms
* first. The checks, the worktree removal and what it leaves behind (the branch, the committed
* `LOGS.md` line, the conversation record) are all {@link deleteProjectRun}'s; this adds only the
* daemon step of stopping a preview that may be serving the worktree before it comes off disk.
*/
export declare function sendDeleteSession(projectId: string, runId: string): Promise<DeleteSessionResult>;
/**
* Start a run in the project (#405, #345): the one write that needs the daemon, since
* spawning goes through the daemon's own `startRun` closure (with its one-run-per-
* project busy guard). The daemon provides `startRun` on the Telefunc request context,
* so this runs in-process. `kind` defaults to a plain build run; a `build`/`prompt`
* needs a non-empty prompt, `research` may be empty (its "what" defaults server-side).
* Returns the daemon's {@link StartRunResult} — `busy` when a run is already active.
*/
export declare function sendStart(projectId: string, prompt: string, kind?: StartRunKind, options?: StartRunOptions): Promise<StartRunResult>;
/**
* Start a project-less "topic" run (#1120): the sibling of {@link sendStart} that takes no project.
* It spawns in a neutral scratch dir with no repo or worktree — the "ask a question / plan / draft a
* ticket without a repo" path. A separate RPC rather than an absent-projectId overload of `sendStart`,
* which keeps that call's home-default behavior untouched. The daemon takes the topic branch off the
* `topic` option; no `projectId` travels. Returns the same {@link StartRunResult} as `sendStart`.
*/
export declare function sendStartTopic(prompt: string, kind?: StartRunKind, options?: StartRunOptions): Promise<StartRunResult>;
/**
* Open a project's Preview (#475): serve its built result on demand and return the live URL.
* The daemon provides the Preview handlers on the request context, so this runs in-process
* (like `sendStart`). Idempotent — opening while a preview is up returns the running one.
* Returns an error result when Preview is not enabled on this host (the relay/per-run view).
*/
export declare function sendPreview(projectId: string, targetId?: string, runId?: string): Promise<PreviewResult>;
/**
* List a project's servable apps (#651) for the Serve picker: the root plus each workspace package
* that has a dev/serve script. A single-package repo returns at most one, so the button stays a
* plain Serve; a monorepo returns several to choose from. Empty when Preview is not enabled.
*/
export declare function onServeTargets(projectId: string, runId?: string): Promise<ServeTarget[]>;
/** Stop a project's Preview (#475). A no-op when none is running, or Preview is not enabled. */
export declare function sendStopPreview(projectId: string, runId?: string): Promise<void>;
/** Report whether a project's Preview is already running (#475), so a reload rehydrates the button. */
export declare function onPreviewStatus(projectId: string, runId?: string): Promise<PreviewStatus>;
/**
* Open a project in the OS file manager or an editor (#490). Localhost-only: the daemon
* spawns a local command against the project's own registered path. A public host has no
* local path to resolve, so it returns an error rather than spawning anything.
*
* With a `runId` it opens that session's own checkout instead (#798) — the whole point of
* opening it is to look at what the agent is doing, which is not in the project's tree.
*/
export declare function sendOpenInApp(projectId: string, target: OpenTarget, runId?: string): Promise<OpenResult>;
/**
* Push a finished session's branch to `origin` (#799).
*
* A click rather than something the run does on its way out: pushing publishes the agent's work
* to a shared remote under the user's name, which is the user's call.
*/
export declare function sendPushBranch(projectId: string, runId: string): Promise<HandoffResult>;
/**
* Open a PR for a finished session's branch (#799), pushing it first if the remote lacks it.
*
* The title and body come from what the run already recorded: the session name the agent chose
* and the intent the user asked for. Nothing new is invented and nothing extra is asked of the
* user, which is the point of "offer the next step rather than describe it".
*/
export declare function sendOpenPullRequest(projectId: string, runId: string): Promise<HandoffResult>;
/**
* The user's Merge action (#1391): one button, two states of the session it addresses.
*
* A live run gets a `merge` control entry — the run arms the full publish ladder, records the
* human authorization (which the #1363 gate honors instead of demanding the agent's signal), and
* merges at its own natural end (#1390). A finished run has no process to steer, so its open PR
* is merged directly — the answer to the withheld-merge ending, where an agent that never
* signalled left a draft behind. If the run ends between the check and the write, the entry lands
* unread; the ended view then offers the direct merge, so the second click still gets there.
*/
export declare function sendMerge(projectId: string, runId: string): Promise<HandoffResult>;
/** What {@link sendQueueTicket} did: the backlog file written, or why it could not be. */
export interface QueueTicketResult {
ok: boolean;
/** The workspace-relative backlog the entry landed in, when it landed. */
file?: string;
error?: string;
}
/** Which ticket a queued entry came from (#1164), so the entry can point back at it. */
export interface QueuedTicket {
/** The ticket's filename inside `tickets/`, which is its identity. */
file: string;
/** Its own `priority:` key, when it has one, which decides the section the entry lands in. */
priority?: string;
}
/**
* Put a ticket on the project's agent queue (#697), so the next drain run works it.
*
* A direct write rather than a run: the queue is a plain file the dashboard already reads,
* and asking an agent to append one line would cost a turn and could do anything else besides.
* It writes the project checkout's flat backlog specifically, which is the durable queue #624
* settled on and the one a worktree run's queue is promoted into (#852).
*
* Given a `ticket`, the entry is placed in the matching `## Priority N` section rather than
* appended to the end of the file, and it links back to the ticket it came from. Both halves of
* #1164: the entry used to land last in a file the drain preset works front to back, and it
* carried nothing but a title, so the ticket it came from was lost the moment it was queued.
*/
/**
* Release a ticket's `.lock.md` claim by hand (#1420): the dashboard's answer to a dead agent,
* since no timer frees locks anymore. Deletes the lock in the project checkout, commits, and
* pushes best-effort ({@link releaseTicketLock}) — a release only this machine can see would
* leave the ticket claimed everywhere the claim matters.
*/
export declare function sendReleaseTicketLock(projectId: string, ticket: string): Promise<{
ok: boolean;
error?: string;
}>;
export declare function sendQueueTicket(projectId: string, entry: string, ticket?: QueuedTicket): Promise<QueueTicketResult>;
//# sourceMappingURL=control.telefunc.d.ts.map