@acryldev/blends-frame 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +105 -2
  3. package/cordis.patch.yml +3 -0
  4. package/lib/app-generation.d.ts +38 -0
  5. package/lib/app-generation.js +101 -0
  6. package/lib/app-generation.js.map +1 -0
  7. package/lib/app-plugins.d.ts +145 -0
  8. package/lib/app-reload.d.ts +74 -0
  9. package/lib/app-snapshot.d.ts +40 -0
  10. package/lib/app-urls.d.ts +17 -0
  11. package/lib/applied-live.d.ts +43 -0
  12. package/lib/auto-save.d.ts +63 -0
  13. package/lib/branch-chats.d.ts +37 -0
  14. package/lib/client.js +50422 -0
  15. package/lib/client.js.map +1 -0
  16. package/lib/contract.d.ts +414 -0
  17. package/lib/git-sync.d.ts +52 -0
  18. package/lib/github-connect.d.ts +44 -0
  19. package/lib/graph-contract.d.ts +85 -0
  20. package/lib/graph-inspect.d.ts +16 -0
  21. package/lib/index.d.ts +186 -0
  22. package/lib/index.js +4060 -0
  23. package/lib/index.js.map +1 -0
  24. package/lib/outward-guard.d.ts +45 -0
  25. package/lib/plain.d.ts +26 -0
  26. package/lib/plugin-graph.d.ts +38 -0
  27. package/lib/real-chats.d.ts +42 -0
  28. package/lib/registry.d.ts +73 -0
  29. package/lib/selection-context.d.ts +118 -0
  30. package/lib/tool-call-guard.d.ts +104 -0
  31. package/lib/types/client/AppSection.d.ts +10 -0
  32. package/lib/types/client/BlendsFrame.d.ts +52 -0
  33. package/lib/types/client/FileView.d.ts +8 -0
  34. package/lib/types/client/FilesView.d.ts +17 -0
  35. package/lib/types/client/GitView.d.ts +18 -0
  36. package/lib/types/client/GraphView.d.ts +22 -0
  37. package/lib/types/client/LeftPanel.d.ts +71 -0
  38. package/lib/types/client/NameYourApp.d.ts +10 -0
  39. package/lib/types/client/PluginsSection.d.ts +17 -0
  40. package/lib/types/client/RegistryView.d.ts +11 -0
  41. package/lib/types/client/RemoteSync.d.ts +17 -0
  42. package/lib/types/client/RightPanel.d.ts +45 -0
  43. package/lib/types/client/SelectionChip.d.ts +59 -0
  44. package/lib/types/client/SettingsExpand.d.ts +6 -0
  45. package/lib/types/client/SettingsLauncher.d.ts +9 -0
  46. package/lib/types/client/ShareChooser.d.ts +21 -0
  47. package/lib/types/client/ShortcutsRow.d.ts +15 -0
  48. package/lib/types/client/TerminalView.d.ts +7 -0
  49. package/lib/types/client/TurnSaveFooter.d.ts +18 -0
  50. package/lib/types/client/app-reload.d.ts +28 -0
  51. package/lib/types/client/branch-chats.d.ts +71 -0
  52. package/lib/types/client/branches.d.ts +23 -0
  53. package/lib/types/client/canvas/AppCanvas.d.ts +25 -0
  54. package/lib/types/client/canvas/app-canvas.d.ts +59 -0
  55. package/lib/types/client/canvas/picker.d.ts +27 -0
  56. package/lib/types/client/chat-draft.d.ts +15 -0
  57. package/lib/types/client/chat-saves.d.ts +28 -0
  58. package/lib/types/client/chats.d.ts +182 -0
  59. package/lib/types/client/desktop-app.d.ts +65 -0
  60. package/lib/types/client/feedback.d.ts +21 -0
  61. package/lib/types/client/frame-state.d.ts +46 -0
  62. package/lib/types/client/frame-view.d.ts +35 -0
  63. package/lib/types/client/fuzzy.d.ts +23 -0
  64. package/lib/types/client/git-sync.d.ts +39 -0
  65. package/lib/types/client/graph-api.d.ts +11 -0
  66. package/lib/types/client/graph-canvas.d.ts +63 -0
  67. package/lib/types/client/graph-link.d.ts +21 -0
  68. package/lib/types/client/graph-model.d.ts +23 -0
  69. package/lib/types/client/graph-styles.d.ts +3 -0
  70. package/lib/types/client/highlight.d.ts +15 -0
  71. package/lib/types/client/index.d.ts +23 -0
  72. package/lib/types/client/panel-resize.d.ts +29 -0
  73. package/lib/types/client/plain-failure.d.ts +10 -0
  74. package/lib/types/client/plugins-navigator.d.ts +81 -0
  75. package/lib/types/client/registry-api.d.ts +21 -0
  76. package/lib/types/client/registry-list.d.ts +18 -0
  77. package/lib/types/client/selection.d.ts +56 -0
  78. package/lib/types/client/settings-fullscreen.d.ts +13 -0
  79. package/lib/types/client/sidebar-opens.d.ts +36 -0
  80. package/lib/types/client/snapshot.d.ts +11 -0
  81. package/lib/types/client/styles.d.ts +3 -0
  82. package/lib/types/client/switch-request.d.ts +18 -0
  83. package/lib/types/client/tab-sizing.d.ts +31 -0
  84. package/lib/types/client/tabs.d.ts +139 -0
  85. package/lib/types/client/theme-switch.d.ts +27 -0
  86. package/lib/types/client/tools.d.ts +15 -0
  87. package/lib/types/client/versions.d.ts +34 -0
  88. package/lib/types/client/view-state.d.ts +42 -0
  89. package/lib/types/contract.d.ts +414 -0
  90. package/lib/types/graph-contract.d.ts +85 -0
  91. package/lib/types/graph-inspect.d.ts +16 -0
  92. package/package.json +124 -3
@@ -0,0 +1,45 @@
1
+ /**
2
+ * The agent never sends the person's work out of the machine without their yes.
3
+ *
4
+ * Share and Push in the frame ask first (./app-plugins.ts, ./git-sync.ts); an agent with a shell could still run `git push`, `gh repo create` or
5
+ * `npm publish` itself, and the access mode may let the shell run unasked. This guard reads each shell call before it runs (`tools/pre-execute`)
6
+ * and turns one that pushes or publishes into DSH's own approval prompt (`ask`): the person sees the command and what it does, and it runs only
7
+ * when they allow it once. A policy that already refused the call stays refused. The app's `save_app` tool, which pushes when the app has a remote,
8
+ * asks the same way.
9
+ *
10
+ * It reads the command's words, so it is a seat belt for an honest agent, not a sandbox: a script that pushes from inside is not seen.
11
+ */
12
+ /** What a shell command sends out of the machine (`git push`, `gh repo create`, `npm publish`), or undefined when it sends nothing. */
13
+ export declare function outwardAction(command: string): string | undefined;
14
+ /** The parts of a DSH tool call the guard reads. */
15
+ export interface OutwardExecution {
16
+ readonly name: string;
17
+ readonly arguments?: unknown;
18
+ }
19
+ /** DSH's pre-dispatch decision, the kinds this guard reads and returns. */
20
+ export type OutwardDecision = {
21
+ readonly kind: 'allow';
22
+ } | {
23
+ readonly kind: 'deny';
24
+ readonly reason: string;
25
+ } | {
26
+ readonly kind: 'cancel';
27
+ } | {
28
+ readonly kind: 'ask';
29
+ readonly reason: string;
30
+ readonly displayReason: {
31
+ readonly en: string;
32
+ };
33
+ };
34
+ export interface OutwardEvents {
35
+ on(name: 'tools/pre-execute', listener: (exec: OutwardExecution, next: () => Promise<OutwardDecision>) => Promise<OutwardDecision>): () => void;
36
+ }
37
+ /** The approval the person sees: what runs and why it asks. */
38
+ export declare function outwardQuestion(action: string, command: string | undefined): string;
39
+ /** What a call needs: the approval to ask, or undefined when it sends nothing out. */
40
+ export declare function outwardApproval(exec: OutwardExecution): {
41
+ readonly action: string;
42
+ readonly command?: string;
43
+ } | undefined;
44
+ /** Listen on DSH's pre-dispatch stage; returns the disposer. */
45
+ export declare function guardOutwardCommands(events: OutwardEvents, report: (line: string) => void): () => void;
package/lib/plain.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * What the person reads when sharing or adding a plugin goes wrong or cannot start: plain words and the one thing to do, never a git line, a stack or a
3
+ * tool's own message. The technical text is kept next to it as `details`, behind a "Details" toggle for developers, so nothing is lost.
4
+ */
5
+ import type { GithubReadiness } from './contract.ts';
6
+ export type { GithubReadiness };
7
+ /** A message for a person and, for a developer, what the tool said. */
8
+ export interface Plain {
9
+ readonly say: string;
10
+ readonly details?: string;
11
+ }
12
+ /** A failure whose message is already for the person; a route answers it as it is. */
13
+ export declare class PlainError extends Error {
14
+ readonly plain: Plain;
15
+ constructor(plain: Plain);
16
+ }
17
+ export declare const GITHUB_MISSING: GithubReadiness;
18
+ export declare const GITHUB_SIGNED_OUT: GithubReadiness;
19
+ /** What a failed tool call says about the person's setup: the helper is not installed, or it is not signed in. */
20
+ export declare function githubProblemOf(message: string): 'missing' | 'signed-out' | undefined;
21
+ /** Read whether sharing to GitHub can work: ask who is signed in. `login` is the host's own check (it throws a tool message when it cannot). */
22
+ export declare function githubReadiness(login: () => string): GithubReadiness;
23
+ /** A share that could not be planned or sent, in words a person can act on. */
24
+ export declare function plainShareProblem(cause: unknown): Plain;
25
+ /** Why a plugin could not be added to the app, by the kind of refusal the app's pull gives (`plugins/plugin-share/pull-check.ts`). */
26
+ export declare function plainPullRefusal(refusal: string, reason: string, next: string): Plain;
@@ -0,0 +1,38 @@
1
+ import type { Context } from '@deepseek-ai/cordis';
2
+ import type { GraphEvent, GraphEventsAnswer, GraphView } from './graph-contract.ts';
3
+ import { type SourceOf } from './graph-inspect.ts';
4
+ export { inspectCordisContext, type SourceOf } from './graph-inspect.ts';
5
+ /** How long a request for events waits for one before it answers with none; the browser asks again at once. */
6
+ export declare const EVENTS_WAIT_MS = 20000;
7
+ /** The recent fiber changes, numbered; a request for those after a number waits for the next change when there are none. */
8
+ export declare class GraphRecorder {
9
+ private seq;
10
+ private readonly events;
11
+ private readonly waiting;
12
+ /** The newest event number; 0 before the first. */
13
+ get head(): number;
14
+ record(event: Omit<GraphEvent, 'seq' | 'at'>, at?: number): void;
15
+ /** Every recorded event after `after`, oldest first. */
16
+ since(after: number): GraphEventsAnswer;
17
+ /** The events after `after`, as soon as there are some; none when `ms` passes first or `signal` aborts (the browser left). */
18
+ wait(after: number, ms: number, signal?: AbortSignal): Promise<GraphEventsAnswer>;
19
+ /** Wake every waiting request now (the Host is stopping); each answers with what it has. */
20
+ release(): void;
21
+ }
22
+ /** Record every fiber of `ctx`'s tree changing: created, removed, or moved to another phase. Returns the stop. */
23
+ export declare function recordFibers(ctx: Context, recorder: GraphRecorder): () => void;
24
+ /**
25
+ * Find where a Loader entry's code is. In the order the app itself finds it: a folder of the app's `plugins/` named like the row, then a path from the app's
26
+ * folder (`./src/frame.ts`), then a package the app or the frame (for the DSH packages, which the frame's own install carries) can resolve.
27
+ */
28
+ export declare function sourceFinder(appRoot: string): SourceOf;
29
+ /** What the routes need: the graph now, and the changes after a number. */
30
+ export interface GraphPort {
31
+ read(): GraphView;
32
+ events(after: number, signal?: AbortSignal): Promise<GraphEventsAnswer>;
33
+ }
34
+ /** The graph of the Host's context, with its recorder started. `stop` ends the recording and answers every waiting request. */
35
+ export declare function createGraphPort(ctx: Context, appRoot: string): {
36
+ readonly port: GraphPort;
37
+ readonly stop: () => void;
38
+ };
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Which chats are real, and what each is called. A chat is real when it has at least one turn. DSH's session list marks a chat `blank` only while it is
3
+ * loaded and carries no title for one that is not, so the list alone cannot tell an old empty chat from a used one or name it; the Host reads each
4
+ * session's log once for both: a `turn/start`, and the title (DSH's own `session/title` event, else the person's first message, cut short).
5
+ * A chat with a title DSH or the person gave is final; one named from its first message is read again after a while, since DSH's title may follow.
6
+ */
7
+ /** The longest a chat's name is in the left panel, in characters, before it is cut at a word. */
8
+ export declare const CHAT_TITLE_LIMIT = 32;
9
+ /** What the frame reads from a session log's events. */
10
+ export interface LogEvent {
11
+ readonly type: string;
12
+ readonly data?: unknown;
13
+ }
14
+ export interface ChatLook {
15
+ readonly hasTurn: boolean;
16
+ /** The chat's name; undefined when the log has neither a title nor a user message. */
17
+ readonly title: string | undefined;
18
+ /** True when DSH or the person named the chat (the title will not change by itself). */
19
+ readonly named: boolean;
20
+ }
21
+ export declare function lookAtLog(events: readonly LogEvent[]): ChatLook;
22
+ export interface RealChat {
23
+ readonly id: string;
24
+ readonly title: string;
25
+ }
26
+ export interface RealChatsDeps {
27
+ /** The ids of every session DSH knows. */
28
+ list(): Promise<readonly string[]>;
29
+ /** One read of the session's log. */
30
+ look(id: string): Promise<ChatLook>;
31
+ readonly report?: (cause: unknown) => void;
32
+ /** How long a chat named from its first message waits before it is read again, in milliseconds. */
33
+ readonly refreshMs?: number;
34
+ readonly now?: () => number;
35
+ }
36
+ export declare class RealChats {
37
+ private readonly deps;
38
+ private readonly known;
39
+ constructor(deps: RealChatsDeps);
40
+ /** The chats with a turn, in the order DSH lists them. A session that cannot be read is left out this time and asked again next time. */
41
+ read(): Promise<RealChat[]>;
42
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The public plugin registry as the frame reads it. cordisplugins.github.io lists a plugin by its public GitHub repository: the repository has the topic
3
+ * `cordis-plugin` and its latest release has one packed copy; the site's sync finds it within the hour and publishes `registry/index.json`
4
+ * (formatVersion 1, one entry per plugin). This reads that file, on the Host: no token, no GitHub search, and a page of the app never fetches it.
5
+ * When the file cannot be read the answer says so in plain words, and a copy read earlier is still shown.
6
+ */
7
+ import type { RegistryEntryView, RegistryView } from './contract.ts';
8
+ export declare const REGISTRY_INDEX_URL = "https://cordisplugins.github.io/registry/index.json";
9
+ type FetchLike = (input: string, init?: {
10
+ readonly signal?: AbortSignal;
11
+ readonly headers?: Record<string, string>;
12
+ }) => Promise<{
13
+ readonly ok: boolean;
14
+ readonly status: number;
15
+ json(): Promise<unknown>;
16
+ }>;
17
+ /** A plugin's folder name: the name without its scope, lower case (`@owner/notes` is `notes`). */
18
+ export declare const bareName: (name: string) => string;
19
+ /** What the app already has and who the person is, so a row can say "Added" and "Yours". */
20
+ export interface RegistryMarks {
21
+ /** The folder names of the app's plugins. */
22
+ readonly names: ReadonlySet<string>;
23
+ /** `owner/repo` (lower case) of every plugin the app pulled. */
24
+ readonly repos: ReadonlySet<string>;
25
+ /** GitHub accounts that are the person's own (signed in, or the share account), lower case. */
26
+ readonly accounts: ReadonlySet<string>;
27
+ }
28
+ /** `owner/repo` of a `github:` source, lower case; undefined for any other source. */
29
+ export declare function repoOfSource(source: string): string | undefined;
30
+ /** The unpacked size of the native package an entry brings for this computer: its OS and CPU first, then its OS for any CPU (plugin-share/native.ts). */
31
+ export declare function downloadFor(native: unknown, platform?: string, arch?: string): number | undefined;
32
+ /**
33
+ * The entries a Blends app can pull: the ones the index gives a version and a pull line (a plugin whose code is only a folder of another
34
+ * repository has none). @throws when the index is not formatVersion 1.
35
+ */
36
+ export declare function registryEntries(index: unknown, marks: RegistryMarks): RegistryEntryView[];
37
+ /** The raw index, read once in a while: a fresh copy within `ttlMs`, else a new read, else the copy read before with the time it was read. */
38
+ export declare function createRegistryReader(fetcher: FetchLike, options?: {
39
+ readonly ttlMs?: number;
40
+ readonly timeoutMs?: number;
41
+ readonly now?: () => number;
42
+ }): () => Promise<{
43
+ readonly index: unknown;
44
+ readonly readAt: string;
45
+ } | {
46
+ readonly message: string;
47
+ }>;
48
+ /** The registry as the frame shows it, from one read of the index. */
49
+ export declare function readRegistryView(read: ReturnType<typeof createRegistryReader>, marks: () => Promise<RegistryMarks>): Promise<RegistryView>;
50
+ /** What one pull answers, as the app's `pluginShare` gives it: the plugin now running, or why it was refused (`plugins/plugin-share/pull-check.ts`). */
51
+ export type PullAnswer = {
52
+ readonly ok: true;
53
+ readonly name: string;
54
+ readonly version: string;
55
+ readonly action: 'installed' | 'updated' | 'unchanged';
56
+ readonly state: string;
57
+ } | {
58
+ readonly ok: false;
59
+ readonly refusal: string;
60
+ readonly reason: string;
61
+ readonly next: string;
62
+ };
63
+ /** The slice of the app's `pluginShare` service the registry uses. */
64
+ export interface PluginShareSlice {
65
+ pull(source: string): Promise<PullAnswer>;
66
+ list(): readonly {
67
+ readonly name: string;
68
+ readonly pulledFrom?: string;
69
+ }[];
70
+ }
71
+ /** The running app's `pluginShare`, read at each call (the app's rows come and go with a reload); undefined when the app has none. */
72
+ export declare function pluginShareOf(service: () => unknown): PluginShareSlice | undefined;
73
+ export {};
@@ -0,0 +1,118 @@
1
+ /**
2
+ * The element a chat message is about, delivered to the agent as a durable context message (docs/design/blends-frame-mockup.html, scenario 2).
3
+ *
4
+ * The composer's send gesture posts the pick to the Host out of band (./contract.ts, {@link FRAME_SELECTION_PATH}), keyed by session; the next
5
+ * `agent/pre-step` of that session takes it once and queues a user-role message whose source is not `user`, the way `dsh-time-context` and
6
+ * `dsh-session-reference` add theirs. The person's message keeps exactly their words: the chat renders the pick as its own small context row,
7
+ * named after the element, instead of carrying a block of text in the bubble.
8
+ *
9
+ * The pick belongs to the message that started the step. The send gesture posts before the message reaches the Host, so a pick stored after that
10
+ * message arrived cannot be its context; it is refused rather than attached to the next turn. A pick nobody claimed within {@link MAX_AGE_MS} is
11
+ * dropped for the same reason. A pick the Host never receives costs the context, never the message: the frame never touches the draft.
12
+ */
13
+ import { type ContextFormed } from '@deepseek-ai/dsh-llm';
14
+ declare module '@deepseek-ai/dsh-llm' {
15
+ interface MessageSourceMap {
16
+ /** The element a message from the person is about; one producer, one form (see ./selection-context.ts). */
17
+ 'acryl-selection': {
18
+ kind: 'acryl-selection';
19
+ } & ContextFormed;
20
+ }
21
+ }
22
+ /** One element picked in the app's canvas, as the message about it carries it. */
23
+ export interface SelectionContext {
24
+ /** The element's short name (`"Fix the invite link"`), the only part the chat's context row shows. */
25
+ readonly label: string;
26
+ /** The app page the canvas showed, with its query. */
27
+ readonly page: string;
28
+ /** A CSS selector that finds the element in that page. */
29
+ readonly selector: string;
30
+ }
31
+ export declare const SELECTION_LIMITS: {
32
+ /** The label is clipped by the picker; the Host only refuses what cannot be one. */
33
+ readonly label: 120;
34
+ readonly page: 500;
35
+ readonly selector: 500;
36
+ };
37
+ /** How long a pick waits for its step before it is dropped: a message is read within seconds of its send. */
38
+ export declare const MAX_AGE_MS = 120000;
39
+ /** One selection as the frame's client posted it; a string says what is wrong. */
40
+ export declare function parseSelectionContext(body: unknown): SelectionContext | string;
41
+ /** The session a posted selection belongs to, or undefined when the body names none. */
42
+ export declare function sessionOf(body: unknown): string | undefined;
43
+ /**
44
+ * What the agent reads: one line naming the element, its page and its selector, guarded as page data. The chat's context row is named by the
45
+ * source instead (the kind carries the label), so this line is what the expanded row shows and what the model gets.
46
+ */
47
+ export declare function selectionModelText(selection: SelectionContext): string;
48
+ /**
49
+ * The durable source of the injected message: a stable producer kind, and a notice form whose one-line summary is what the chat's collapsed row
50
+ * shows ("Selected: <label>"). The page and selector stay in the model-facing content, which the row shows only when someone expands it.
51
+ */
52
+ export declare function selectionSource(selection: SelectionContext): {
53
+ readonly kind: 'acryl-selection';
54
+ readonly form: 'notice';
55
+ readonly summary: string;
56
+ };
57
+ /** The picks waiting for their step, one per session, consumed once. */
58
+ export declare class SelectionInbox {
59
+ private readonly pending;
60
+ /** Record the pick a send gesture made; a newer pick of the same session replaces the older one. */
61
+ add(session: string, selection: SelectionContext, now?: number): void;
62
+ /**
63
+ * Take the pick that belongs to a message the session logged at `messageAt`.
64
+ * @param session - the chat's session id.
65
+ * @param messageAt - when the session's newest human message was logged.
66
+ * @param now - the host's clock.
67
+ * @returns the pick, once; undefined when there is none, it came after that message, or it waited too long.
68
+ */
69
+ take(session: string, messageAt: number, now?: number): SelectionContext | undefined;
70
+ /** For tests and diagnostics: how many picks wait. */
71
+ get size(): number;
72
+ }
73
+ /** The part of one logged session event the frame reads: its type, when it happened, and its data. */
74
+ export interface SessionEventLike {
75
+ readonly type: string;
76
+ readonly time: number;
77
+ readonly data: unknown;
78
+ }
79
+ /** The part of a DSH session the frame reads: how far it has logged, and one event by its position. */
80
+ export interface SessionLike {
81
+ readonly id: string;
82
+ readonly seq: number;
83
+ eventAt(seq: number): SessionEventLike | undefined;
84
+ }
85
+ /**
86
+ * When the session's newest message from the person was logged.
87
+ * @param session - the chat's session.
88
+ * @param scan - how many of the newest events to read; a turn of tool calls can be long.
89
+ * @returns the event time, or undefined when the session has no human message yet.
90
+ */
91
+ export declare function lastHumanMessageAt(session: SessionLike, scan?: number): number | undefined;
92
+ /** Whether and with which messages the loop enters a step. */
93
+ export type PreStepDecision = {
94
+ readonly kind: 'reject';
95
+ } | {
96
+ readonly kind: 'enter';
97
+ readonly messages: readonly unknown[];
98
+ };
99
+ /** The pre-step payload the frame reads: the agent (and so its session), the turn and the step. */
100
+ export interface PreStepPayload {
101
+ readonly agent: {
102
+ readonly session: SessionLike;
103
+ };
104
+ readonly turn: number;
105
+ readonly step: number;
106
+ }
107
+ /** `ctx.on('agent/pre-step', ...)`: DSH's agent-scoped waterfall before each model step. */
108
+ export interface PreStepEvents {
109
+ on(name: 'agent/pre-step', listener: (payload: PreStepPayload, next: () => Promise<PreStepDecision>) => Promise<PreStepDecision>): () => void;
110
+ }
111
+ /**
112
+ * Take a waiting pick at the step that reads the message it belongs to, and queue it as context.
113
+ * @param ctx - the frame's host context, whose events are DSH's.
114
+ * @param inbox - the picks posted by the frame's client.
115
+ * @param report - where a refused pick is logged.
116
+ * @returns the disposer of the listener.
117
+ */
118
+ export declare function installSelectionContext(ctx: object, inbox: SelectionInbox, report: (cause: unknown) => void): () => void;
@@ -0,0 +1,104 @@
1
+ /**
2
+ * A tool call can never hold a builder's chat forever.
3
+ *
4
+ * DSH's agent loop awaits each stage of a tool call in turn, and its registry never abandons a stage's promise: a policy gate or a wrapper that does
5
+ * not settle leaves the turn running with no process and no prompt, past the command's own timeout (which only arms inside the execute stage), and
6
+ * the Stop button cannot end it either. This guard sits outside each stage and gives it a limit:
7
+ *
8
+ * - Before the tool runs (`tools/pre-execute`, every tool): over the limit, or on Stop, the call is refused without running. An approval is asked
9
+ * after this stage, so a person deciding is not counted.
10
+ * - While a command runs (`tools/execute`, the shell tools): its own timeout plus a grace. A command past its timeout returns by itself (DSH keeps it
11
+ * as a job), so reaching this limit means the call is stuck. The command is asked to stop, then the call ends with a sentence that says what happened.
12
+ * Stop is given the same short wait. While a person has a prompt open in that chat the limit waits for them.
13
+ * - After the tool ran (`tools/post-execute`, every tool): over the limit, the result is kept as it is.
14
+ *
15
+ * Each firing is reported with the stage and the tool, which is what the next stall needs for its root cause.
16
+ *
17
+ * One more thing can end a chat for good: an agent stopping the app's Host, which is the process running it and the frame. A shell command that kills
18
+ * that process (by its id, its port or its script) is refused with what to do instead. It is a seat belt for an honest mistake, not a sandbox.
19
+ */
20
+ export declare const PREPARE_LIMIT_MS = 120000;
21
+ export declare const FINISH_LIMIT_MS = 60000;
22
+ /** Past a command's timeout: what its kill escalation, its output and the session's flush may take before the call counts as stuck. */
23
+ export declare const COMMAND_GRACE_MS = 60000;
24
+ /** How long a command that was told to stop may take to return. */
25
+ export declare const STOP_WAIT_MS = 5000;
26
+ export declare const TOOL_CALL_STALLED = "TOOL_CALL_STALLED";
27
+ /** The parts of a DSH tool execution the guard reads; `signal` it replaces for the stage, as DSH's own timeout policy does. */
28
+ export interface GuardedExecution {
29
+ readonly name: string;
30
+ readonly arguments?: unknown;
31
+ readonly agent?: {
32
+ readonly session: {
33
+ readonly id: string;
34
+ };
35
+ };
36
+ signal: AbortSignal;
37
+ }
38
+ /** The stalled call's result, in the shape DSH's timeout policy uses. */
39
+ export interface StalledResult {
40
+ readonly content: readonly [{
41
+ readonly type: 'text';
42
+ readonly text: string;
43
+ }];
44
+ readonly isError: true;
45
+ readonly error: {
46
+ readonly message: string;
47
+ readonly info: {
48
+ readonly name: string;
49
+ readonly code: string;
50
+ };
51
+ };
52
+ }
53
+ type Decision = {
54
+ readonly kind: 'deny';
55
+ readonly reason: string;
56
+ } | {
57
+ readonly kind: 'cancel';
58
+ } | {
59
+ readonly kind: 'accept';
60
+ } | object;
61
+ /** The DSH events the guard listens on; each `on` returns its disposer. */
62
+ export interface ToolCallEvents {
63
+ on(name: 'tools/pre-execute', listener: (exec: GuardedExecution, next: () => Promise<Decision>) => Promise<Decision>, options: {
64
+ prepend: true;
65
+ }): () => void;
66
+ on(name: 'tools/execute', listener: (exec: GuardedExecution, next: () => Promise<object>) => Promise<object>, options: {
67
+ prepend: true;
68
+ }): () => void;
69
+ on(name: 'tools/post-execute', listener: (exec: GuardedExecution, result: unknown, next: () => Promise<Decision>) => Promise<Decision>, options: {
70
+ prepend: true;
71
+ }): () => void;
72
+ on(name: 'session/event', listener: (session: {
73
+ readonly id: string;
74
+ }, event: {
75
+ readonly type: string;
76
+ readonly data: unknown;
77
+ }) => void): () => void;
78
+ }
79
+ /** The limit of a shell call's execute stage; undefined for any other tool, whose run has no length to hold it to. */
80
+ export declare function commandLimitMs(exec: Pick<GuardedExecution, 'name' | 'arguments'>): number | undefined;
81
+ export declare function stalledResult(toolName: string, why: 'stuck' | 'stopped', limitMs: number): StalledResult;
82
+ /** The Host this guard runs in, as a shell command would name it. */
83
+ export interface HostIdentity {
84
+ readonly hostPid: number;
85
+ readonly hostPort?: number;
86
+ /** The Host's process group: `kill 0`, `kill -- -<id>` or `pkill -g <id>` ends it too. */
87
+ readonly hostGroupId?: number;
88
+ /** The Host's own command line (`process.execPath` and its arguments), for `pkill -f` patterns. */
89
+ readonly hostCommand?: string;
90
+ /** The Host's process name, for `pkill`/`killall` without `-f`. */
91
+ readonly hostName?: string;
92
+ }
93
+ /** Whether a shell call would stop the Host. A kill alone is fine: agents stop their own test servers. */
94
+ export declare function stopsHost(exec: Pick<GuardedExecution, 'name' | 'arguments'>, host: HostIdentity): boolean;
95
+ export declare const HOST_REFUSAL = "that command could stop the app's Host, the process running this chat and the page beside it: it names the Host, its process group, all node processes, or a pattern that matches it. It was not run. To restart only a process you started, stop that process by its own id (kill <pid>) and start it again; never a group, a name like node, or a broad -f pattern. A saved change in src/ or plugins/ reloads the app by itself; if a change does not show, the reload failed, so read the error and fix it.";
96
+ /**
97
+ * Put the guard on the tool calls of every chat.
98
+ * @param events - the plugin's context, as the events it listens on.
99
+ * @param report - hears each firing.
100
+ * @param host - the Host to protect from a shell command; left out, nothing is refused.
101
+ * @returns the disposer: the listeners and every running limit stop.
102
+ */
103
+ export declare function guardToolCalls(events: ToolCallEvents, report: (line: string) => void, host?: HostIdentity): () => void;
104
+ export {};
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Settings > App, in a desktop product: the app's name, its folder and size, export, import, the other apps on this computer, start over, and the
3
+ * licence of the git the product ships. Laid out as the Plugins page is (docs/design/blends-frame-mockup.html): a title, one line under it, one bordered
4
+ * row per thing. Start over asks inside the page, and Cancel is what a stray Enter or click does.
5
+ */
6
+ import { type DesktopApp } from './desktop-app.ts';
7
+ export interface AppSectionInjected {
8
+ readonly app: DesktopApp;
9
+ }
10
+ export declare function AppSection({ app }: AppSectionInjected): import("react").JSX.Element;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * The Blends frame (docs/design/blends-frame-mockup.html): a top bar; on the left the branches with what is open on them, and the versions; the
3
+ * app alone in the centre; on the right the agents as tabs. Nothing of the IDE's workbench is here - no projects, tab strip of tiles, dock or start
4
+ * page. DSH renders only inside it: the chat is the keyed `main` entry `conversation` in the right panel, and a keyed panel DSH opens (Settings)
5
+ * covers the frame as a dialog.
6
+ */
7
+ import type { PropsRenderSlots, PropsRuntime } from '@acryldev/ui/frame';
8
+ import type { DesktopLayoutState } from '@acryldev/app-shell/client';
9
+ import type { AppCanvasState } from './canvas/app-canvas.ts';
10
+ import type { AppReloadStore } from './app-reload.ts';
11
+ import type { FrameStateStore } from './frame-state.ts';
12
+ import type { SelectionStore } from './selection.ts';
13
+ import type { FrameViewState } from './view-state.ts';
14
+ import { type BranchesPort, type ChatsPort, type FeedbackPort } from './LeftPanel.tsx';
15
+ import type { BranchChatsPort } from './branch-chats.ts';
16
+ import { type VersionsPort } from './versions.ts';
17
+ import type { GitSyncPort } from './git-sync.ts';
18
+ import { type SidebarPort } from './RightPanel.tsx';
19
+ import type { FrameTabs } from './tabs.ts';
20
+ import type { SwitchRequests } from './switch-request.ts';
21
+ import type { FrameTools } from './tools.ts';
22
+ import type { DesktopApp } from './desktop-app.ts';
23
+ import type { ThemeSwitch } from './theme-switch.ts';
24
+ export interface BlendsFrameInjected {
25
+ readonly layout: DesktopLayoutState;
26
+ /** DSH's right sidebar, drawn in the right panel's Panel tab. */
27
+ readonly sidebar: SidebarPort;
28
+ readonly canvas: AppCanvasState;
29
+ readonly selection: SelectionStore;
30
+ readonly frameState: FrameStateStore;
31
+ /** Whether the app's last code was refused (a syntax error): the bar says so while the canvas keeps the last good app. */
32
+ readonly appReload: AppReloadStore;
33
+ readonly view: FrameViewState;
34
+ /** The Dark/Light switch in the top bar. */
35
+ readonly themeSwitch: ThemeSwitch;
36
+ readonly chats: ChatsPort;
37
+ readonly versions: VersionsPort;
38
+ /** The Git tab's push and pull (the Host runs git). */
39
+ readonly gitSync: GitSyncPort;
40
+ readonly tabs: FrameTabs;
41
+ readonly tools: FrameTools;
42
+ readonly feedback: FeedbackPort;
43
+ readonly branches: BranchesPort;
44
+ /** Which branch each chat was opened on (DSH keeps no branches; the Host records it). */
45
+ readonly branchChats: BranchChatsPort;
46
+ /** A chat of another branch asked for from the chat's History: the left panel offers the switch. */
47
+ readonly switchRequests: SwitchRequests;
48
+ /** A desktop product's app (`./desktop-app.ts`): the bar shows the name the person gave it. */
49
+ readonly desktop?: DesktopApp;
50
+ }
51
+ export type BlendsFrameProps = PropsRuntime<'root'> & PropsRenderSlots<'main' | 'rightbar' | 'shell.overlay' | 'sidebar.settings'> & BlendsFrameInjected;
52
+ export declare function BlendsFrame({ layout, sidebar, canvas, selection, frameState, appReload, view, themeSwitch, chats, versions, gitSync, tabs, tools, feedback, branches, branchChats, switchRequests, desktop, renderSlot }: BlendsFrameProps): import("react").JSX.Element;
@@ -0,0 +1,8 @@
1
+ /** A file tab: the file as text, with line numbers and syntax colours. Read when the tab is shown. */
2
+ import type { WorkspaceFilesApi } from '@acryldev/workspace/ui';
3
+ export interface FileViewProps {
4
+ readonly files: WorkspaceFilesApi;
5
+ readonly root: string;
6
+ readonly path: string;
7
+ }
8
+ export declare function FileView({ files, root, path }: FileViewProps): import("react").JSX.Element;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The Files tab: a fuzzy search over every file of the app (⌘P anywhere), then the folder tree. A file opens as its own tab. Ignored files (build
3
+ * output, dependencies) are left out of both, as in the mockup.
4
+ */
5
+ import type { WorkspaceFilesApi } from '@acryldev/workspace/ui';
6
+ /** The window event ⌘P sends: the Files tab is shown and its search takes the keys. */
7
+ export declare const FILES_SEARCH_EVENT = "acryl-blends:files-search";
8
+ export interface FilesViewProps {
9
+ readonly files: WorkspaceFilesApi;
10
+ readonly root: string;
11
+ /** The file open as a tab, if any: its folders are expanded and its row marked. */
12
+ readonly current?: string | undefined;
13
+ readonly openFile: (path: string) => void;
14
+ }
15
+ /** The folders above a file, outermost first: `src/a/b.ts` gives `src`, `src/a`. */
16
+ export declare function foldersAbove(path: string): string[];
17
+ export declare function FilesView({ files, root, current, openFile }: FilesViewProps): import("react").JSX.Element;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The Git tab: the branch against its remote with Push and Pull, what changed since the newest version, then the versions as history. Read
3
+ * again whenever the frame sees a new head or count; the remote is asked (a fetch) when the tab opens and by each push or pull.
4
+ */
5
+ import type { WorkspaceGitApi } from '@acryldev/workspace/ui';
6
+ import type { GitSyncPort } from './git-sync.ts';
7
+ import { type VersionsPort } from './versions.ts';
8
+ export interface GitViewProps {
9
+ readonly git: WorkspaceGitApi;
10
+ readonly versions: VersionsPort;
11
+ readonly sync: GitSyncPort;
12
+ readonly root: string;
13
+ /** Changes when the worktree does (the frame state's head and unsaved count): the tab reads again. */
14
+ readonly revision: string;
15
+ }
16
+ /** The letter a change shows: git's own, with an untracked file as U (new), as editors show it. */
17
+ export declare const changeLetter: (code: string) => string;
18
+ export declare function GitView({ git, versions, sync, root, revision }: GitViewProps): import("react").JSX.Element;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Settings > Plugins > Graph: every plugin of the running app (and of the frame around it) as a picture, with how they depend on each other, and a line for
3
+ * each change as it happens. Ported from cordis-plugin-graph's `GraphTab.tsx` (MIT, commit e9bf6b5): the planes, the three relation toggles, the filter, the
4
+ * counts and the detail card are its. New here: the picture is updated in place and the Host's fiber events arrive by a waiting request, not by asking every
5
+ * two seconds; a changed plugin pulses; the strip lists the changes; the card says who a plugin needs and who needs it; and a plugin's code opens in the
6
+ * Files tab from the card.
7
+ */
8
+ import type { GraphEvent, GraphSnapshot } from '../graph-contract.ts';
9
+ import type { GraphApi } from './graph-api.ts';
10
+ /** The browser's own Cordis context, as the view reads it: its graph now, and each fiber change as it happens. */
11
+ export interface ClientGraph {
12
+ inspect(): GraphSnapshot;
13
+ subscribe(listener: (event: Omit<GraphEvent, 'seq' | 'at'>) => void): () => void;
14
+ }
15
+ export interface GraphViewInjected {
16
+ readonly api: GraphApi;
17
+ /** Absent where the browser's context cannot be read: the client plane is then not offered. */
18
+ readonly client?: ClientGraph;
19
+ /** Open a file of the app (a path from the app's folder) in the Files tab. */
20
+ readonly openSource: (path: string) => void;
21
+ }
22
+ export declare function GraphView({ api, client, openSource }: GraphViewInjected): import("react").JSX.Element;