@acryldev/harness-runtime 0.0.0-stage → 0.2.12
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.
- package/LICENSE +49 -0
- package/README.md +14 -2
- package/lib/index.mjs +5693 -0
- package/lib/index.mjs.map +1 -0
- package/lib/types/acryl-home.d.ts +81 -0
- package/lib/types/app/new-app.d.ts +65 -0
- package/lib/types/app/start-source.d.ts +47 -0
- package/lib/types/blueprint/blueprint.d.ts +74 -0
- package/lib/types/blueprint/brand-identity.d.ts +26 -0
- package/lib/types/blueprint/compose.d.ts +53 -0
- package/lib/types/blueprint/definition.d.ts +22 -0
- package/lib/types/blueprint/index.d.ts +7 -0
- package/lib/types/blueprint/manifest.d.ts +35 -0
- package/lib/types/blueprint/selection.d.ts +19 -0
- package/lib/types/cli-market-install.d.ts +97 -0
- package/lib/types/cli-market-plugins.d.ts +81 -0
- package/lib/types/coding-capabilities.d.ts +29 -0
- package/lib/types/durable-message.d.ts +18 -0
- package/lib/types/engine-dsh.d.ts +181 -0
- package/lib/types/engine-files.d.ts +8 -0
- package/lib/types/engine-host.d.ts +32 -0
- package/lib/types/engine-tools.d.ts +11 -0
- package/lib/types/index.d.ts +67 -0
- package/lib/types/instance/announce-self.d.ts +38 -0
- package/lib/types/instance/app-instance.d.ts +125 -0
- package/lib/types/instance/index.d.ts +6 -0
- package/lib/types/instance/offline-lock.d.ts +29 -0
- package/lib/types/instance/online-secret.d.ts +29 -0
- package/lib/types/instance/registry.d.ts +26 -0
- package/lib/types/instance/select.d.ts +43 -0
- package/lib/types/module-hooks.d.ts +19 -0
- package/lib/types/module-resolution.d.ts +31 -0
- package/lib/types/package-overlay.d.ts +41 -0
- package/lib/types/pinned-pnpm.d.ts +15 -0
- package/lib/types/plugin-acryl-workspace-status.d.ts +24 -0
- package/lib/types/plugin-doctor.d.ts +49 -0
- package/lib/types/plugin-lifecycle-state.d.ts +92 -0
- package/lib/types/plugin-lifecycle.d.ts +87 -0
- package/lib/types/profile-layout.d.ts +17 -0
- package/lib/types/profile-owner.d.ts +25 -0
- package/lib/types/profile-repair/backup.d.ts +37 -0
- package/lib/types/profile-repair/findings.d.ts +29 -0
- package/lib/types/profile-repair/index.d.ts +9 -0
- package/lib/types/profile-repair/inspector.d.ts +11 -0
- package/lib/types/profile-repair/repair.d.ts +38 -0
- package/lib/types/profile-resolution/moved-framework.d.ts +21 -0
- package/lib/types/profile-resolution/resolver.d.ts +41 -0
- package/lib/types/profile-resolution/service.d.ts +22 -0
- package/lib/types/prompt-budget.d.ts +44 -0
- package/lib/types/session-bridge.d.ts +57 -0
- package/lib/types/session-log-exporter.d.ts +31 -0
- package/lib/types/system-prompt-capture.d.ts +29 -0
- package/lib/types/web-favicon-data.d.ts +5 -0
- package/lib/types/web-favicon.d.ts +23 -0
- package/lib/types/web-market-install.d.ts +114 -0
- package/lib/types/web-market-plugins.d.ts +106 -0
- package/lib/types/web-port.d.ts +15 -0
- package/package.json +211 -3
- package/src/acryl-home.ts +103 -0
- package/src/app/new-app.ts +239 -0
- package/src/app/start-source.ts +110 -0
- package/src/blueprint/blueprint.ts +141 -0
- package/src/blueprint/brand-identity.ts +75 -0
- package/src/blueprint/compose.ts +222 -0
- package/src/blueprint/definition.ts +92 -0
- package/src/blueprint/index.ts +20 -0
- package/src/blueprint/manifest.ts +145 -0
- package/src/blueprint/selection.ts +74 -0
- package/src/cli-market-install.ts +181 -0
- package/src/cli-market-plugins.ts +176 -0
- package/src/coding-capabilities.ts +61 -0
- package/src/durable-message.ts +23 -0
- package/src/engine-dsh.ts +856 -0
- package/src/engine-files.ts +9 -0
- package/src/engine-host.ts +128 -0
- package/src/engine-tools.ts +26 -0
- package/src/index.ts +436 -0
- package/src/instance/announce-self.ts +88 -0
- package/src/instance/app-instance.ts +240 -0
- package/src/instance/index.ts +45 -0
- package/src/instance/offline-lock.ts +71 -0
- package/src/instance/online-secret.ts +55 -0
- package/src/instance/registry.ts +53 -0
- package/src/instance/select.ts +134 -0
- package/src/module-hooks.ts +41 -0
- package/src/module-resolution.ts +187 -0
- package/src/package-overlay.ts +160 -0
- package/src/pinned-pnpm.ts +67 -0
- package/src/plugin-acryl-workspace-status.ts +99 -0
- package/src/plugin-doctor.ts +141 -0
- package/src/plugin-lifecycle-state.ts +347 -0
- package/src/plugin-lifecycle.ts +223 -0
- package/src/profile-layout.ts +97 -0
- package/src/profile-owner.ts +52 -0
- package/src/profile-repair/backup.ts +119 -0
- package/src/profile-repair/findings.ts +43 -0
- package/src/profile-repair/index.ts +10 -0
- package/src/profile-repair/inspector.ts +156 -0
- package/src/profile-repair/repair.ts +137 -0
- package/src/profile-resolution/moved-framework.ts +64 -0
- package/src/profile-resolution/resolver.ts +876 -0
- package/src/profile-resolution/service.ts +99 -0
- package/src/prompt-budget.ts +118 -0
- package/src/session-bridge.ts +350 -0
- package/src/session-log-exporter.ts +68 -0
- package/src/system-prompt-capture.ts +99 -0
- package/src/web-favicon-data.ts +6 -0
- package/src/web-favicon.ts +43 -0
- package/src/web-market-install.ts +206 -0
- package/src/web-market-plugins.ts +215 -0
- package/src/web-port.ts +39 -0
- package/tests/account-callback.spec.ts +173 -0
- package/tests/acryl-home.spec.ts +39 -0
- package/tests/agent-self-hosting.spec.ts +101 -0
- package/tests/announce-self.spec.ts +84 -0
- package/tests/app-lifecycle.spec.ts +99 -0
- package/tests/blank-blueprint.spec.ts +110 -0
- package/tests/blueprint-definition.spec.ts +128 -0
- package/tests/blueprint.spec.ts +138 -0
- package/tests/bulkhead.spec.ts +187 -0
- package/tests/coding-vocabulary.spec.ts +15 -0
- package/tests/dump-system-prompt.spec.ts +65 -0
- package/tests/e2e-real-model.spec.ts +71 -0
- package/tests/e2e-restart-real-model.spec.ts +77 -0
- package/tests/engine-dsh.spec.ts +340 -0
- package/tests/engine-host-mount-root-include.spec.ts +118 -0
- package/tests/engine-host.spec.ts +176 -0
- package/tests/engine-optional.spec.ts +81 -0
- package/tests/extension-examples.spec.ts +261 -0
- package/tests/hooks-thread-stack.ts +27 -0
- package/tests/instance-patches.spec.ts +25 -0
- package/tests/instance.spec.ts +235 -0
- package/tests/live/community-plugins.spec.ts +83 -0
- package/tests/module-hooks.spec.ts +35 -0
- package/tests/module-resolution.spec.ts +265 -0
- package/tests/moved-framework.spec.ts +61 -0
- package/tests/new-app.spec.ts +132 -0
- package/tests/organizer-growth.spec.ts +117 -0
- package/tests/pinned-pnpm.spec.ts +34 -0
- package/tests/plugin-acryl-workspace-status.spec.ts +63 -0
- package/tests/plugin-context.spec.ts +640 -0
- package/tests/plugin-doctor.spec.ts +183 -0
- package/tests/plugin-enablement-one-store.spec.ts +130 -0
- package/tests/plugin-lifecycle-state.spec.ts +169 -0
- package/tests/profile-layout.spec.ts +58 -0
- package/tests/profile-owner.spec.ts +38 -0
- package/tests/profile-repair/profile-repair.spec.ts +231 -0
- package/tests/profile-resolution-port.spec.ts +30 -0
- package/tests/profile-resolution-service.spec.ts +273 -0
- package/tests/profile-resolution-swap.spec.ts +69 -0
- package/tests/profile-resolution.spec.ts +2535 -0
- package/tests/profile.spec.ts +70 -0
- package/tests/project-registry.spec.ts +81 -0
- package/tests/prompt-budget.spec.ts +58 -0
- package/tests/real-home-guard.spec.ts +178 -0
- package/tests/session-bridge.spec.ts +316 -0
- package/tests/start-source.spec.ts +65 -0
- package/tests/system-prompt-shape.spec.ts +95 -0
- package/tests/three-levels.spec.ts +84 -0
- package/tests/tool-gateway.spec.ts +116 -0
- package/tests/tool-schemas.spec.ts +41 -0
- package/tests/web-favicon.spec.ts +42 -0
- package/tests/web-port.spec.ts +38 -0
- package/tests/web-startup-hold.spec.ts +79 -0
- package/tsconfig.json +24 -0
- package/tsdown.config.ts +2 -0
- package/vitest.config.ts +18 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Input accepted by the runtime-owned durable Harness session bridge. */
|
|
2
|
+
export interface DurableSessionMessage {
|
|
3
|
+
readonly sessionId: string;
|
|
4
|
+
readonly text: string;
|
|
5
|
+
}
|
|
6
|
+
/** Acknowledgement that a message was accepted for durable session processing. */
|
|
7
|
+
export interface DurableSessionMessageReceipt {
|
|
8
|
+
readonly accepted: true;
|
|
9
|
+
readonly sessionId: string;
|
|
10
|
+
readonly messageId: string;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Host-to-runtime boundary for one identified durable Harness session.
|
|
14
|
+
* Implementations belong to the runtime owner, never to a presentation surface.
|
|
15
|
+
*/
|
|
16
|
+
export interface DurableSessionMessagePort {
|
|
17
|
+
dispatch(message: DurableSessionMessage, signal?: AbortSignal): Promise<DurableSessionMessageReceipt>;
|
|
18
|
+
}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `dsh` engine provider (spec 028): mounts the pinned Harness profile as
|
|
3
|
+
* one Loader row under `createAcrylEngineHost`'s persistent root, instead of
|
|
4
|
+
* the second Cordis root `boot()`/`bootAcrylHarnessProfile` creates. Performs
|
|
5
|
+
* the identical composition - the HMR guard, workspace-status/session-log-
|
|
6
|
+
* exporter wiring - so selecting `dsh` behaves exactly like today's direct
|
|
7
|
+
* boot (SC-004).
|
|
8
|
+
*
|
|
9
|
+
* Two entry points share the mounting primitive (`mountDshEngine`) but differ
|
|
10
|
+
* in where the composition comes from: {@link createDshEngineDefinition} is
|
|
11
|
+
* the CLI/TUI flavor, resolving a named profile through this package's own
|
|
12
|
+
* profile system; {@link createDshEngineDefinitionFromComposition} takes an
|
|
13
|
+
* already-resolved `{rootConfig, patches, bareModuleBaseUrl}` a surface with
|
|
14
|
+
* its own profile pipeline (Desktop's `prepareDesktopProfile()`) produced
|
|
15
|
+
* itself. Neither does the other's job.
|
|
16
|
+
*
|
|
17
|
+
* `mountRootInclude` (unlike `boot()`) composes onto an already-initialized
|
|
18
|
+
* Loader rather than creating its own, but it does not scope the Include row
|
|
19
|
+
* it creates to the calling plugin's own fiber - this plugin owns and
|
|
20
|
+
* removes it explicitly via `ctx.effect()`. Verified with a real Loader
|
|
21
|
+
* activation in `tests/engine-host-mount-root-include.spec.ts` before this
|
|
22
|
+
* file trusted the pattern.
|
|
23
|
+
*/
|
|
24
|
+
import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include';
|
|
25
|
+
import { type Profile, type ProfileContext, type RuntimeResolution } from '@deepseek-ai/dsh-app-boot';
|
|
26
|
+
import type { AcrylCodingCapabilityId, AcrylShellMode, AcrylSurface } from './coding-capabilities.ts';
|
|
27
|
+
import type { AcrylEngineDefinition } from './engine-host.ts';
|
|
28
|
+
import { type AppInstance } from './instance/index.ts';
|
|
29
|
+
/** An already-resolved dsh composition: what one surface's own profile pipeline produced. */
|
|
30
|
+
export interface DshEngineComposition {
|
|
31
|
+
readonly rootConfig: string;
|
|
32
|
+
readonly patches: readonly PatchOptions[];
|
|
33
|
+
/** Resolves worker-only bare-module URLs (e.g. `/plugins/...`); omitted when the surface serves no such URLs. */
|
|
34
|
+
readonly bareModuleBaseUrl?: string;
|
|
35
|
+
/** Which ACRYL surface this is (`tui`, `web`, `desktop`) - becomes part of the durable session-log filename. */
|
|
36
|
+
readonly surface: string;
|
|
37
|
+
/** The product name the page title carries (the Blueprint's brand); defaults to `ACRYL`. */
|
|
38
|
+
readonly productName?: string;
|
|
39
|
+
/** The stock ACRYL brand (not a Blueprint's own): the served page wears the ACRYL icon. */
|
|
40
|
+
readonly stockBrand?: boolean;
|
|
41
|
+
/** The app this composition belongs to; provided to plugins as the `appInstance` service. Chosen by the surface's composition root. */
|
|
42
|
+
readonly instance?: AppInstance;
|
|
43
|
+
/** File URL of the surface's own `package.json` (where ACRYL-owned workspace packages resolve from); provided to plugins
|
|
44
|
+
* as the `acrylFrameworkPackages` service. Omitted where materializing an ACRYL framework package into a local
|
|
45
|
+
* extension's profile does not apply (for example, a composition root with its own separate profile pipeline). */
|
|
46
|
+
readonly installPackageUrl?: string;
|
|
47
|
+
/**
|
|
48
|
+
* The package table `@deepseek-ai/dsh-app-boot` computes for this profile (DSH 0.2). Since 0.2 a profile no longer carries link
|
|
49
|
+
* projections of the installation's packages; the `pluginPackages` service (ACRYL's `ProfilePluginPackages`) answers every bare-package import from this table, so
|
|
50
|
+
* the engine mounts it before the profile include. Compute it with {@link createProfileRuntimeResolution} after every
|
|
51
|
+
* ACRYL-owned package has been materialized into the profile.
|
|
52
|
+
*/
|
|
53
|
+
readonly runtimeResolution?: RuntimeResolution;
|
|
54
|
+
/**
|
|
55
|
+
* The profile facts DSH 0.2 reads for live configuration. `config-editor`, `settings` (the Models page, where credentials are
|
|
56
|
+
* entered) and the plugin manager are only enabled while a `profileContext` exists, exactly as stock `dsh` provides one.
|
|
57
|
+
* Never named `desktop`: that name would also switch on upstream's product telemetry rows.
|
|
58
|
+
*/
|
|
59
|
+
readonly profileContext?: ProfileContext;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* The surface's coding-capability composition, handed to an engine definition by the app that owns it: the plugins package for the
|
|
63
|
+
* rows, the package names, the anchor they resolve from, and the rows the advanced shell replaces. `@acryldev/coding-capabilities` is
|
|
64
|
+
* the one implementation; the runtime never imports it (its Blueprint vocabulary lives in `coding-capabilities.ts`).
|
|
65
|
+
*/
|
|
66
|
+
export interface CodingCapabilities {
|
|
67
|
+
/** Installations whose `node_modules` may hold a package the composition names, in order (the surface's, then the composition package's). */
|
|
68
|
+
readonly anchors: readonly string[];
|
|
69
|
+
patches(surface: ReadonlySet<AcrylSurface>, existingRowIds: ReadonlySet<string>, only: ReadonlySet<AcrylCodingCapabilityId>): readonly PatchOptions[];
|
|
70
|
+
shellPatches(surface: ReadonlySet<AcrylSurface>, shellMode: AcrylShellMode, existingRowIds: ReadonlySet<string>, only: ReadonlySet<AcrylCodingCapabilityId>): readonly PatchOptions[];
|
|
71
|
+
/** The ACRYL-owned packages a surface must make resolvable for the capabilities it composes. */
|
|
72
|
+
packages(surface: ReadonlySet<AcrylSurface>, only: ReadonlySet<AcrylCodingCapabilityId>): readonly string[];
|
|
73
|
+
/** The rows the advanced shell replaces (`ADVANCED_SHELL_PATCHES`), for a Blueprint with an `app-shell` row. */
|
|
74
|
+
readonly appFramePatches: readonly PatchOptions[];
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* DeepSeek's own product analytics, which DSH's Web bundle switches on for any profile named `desktop` (Desktop's profile is) and which report
|
|
78
|
+
* to DeepSeek's collector. ACRYL is not that product: they are off on every surface, at the first mount and at every reload, instead of
|
|
79
|
+
* depending on a profile name. Mounted, the Host row also failed its config at every start, since only DeepSeek's shell sets its
|
|
80
|
+
* `serviceVersion` (`DSH_CLIENT_VERSION`).
|
|
81
|
+
*/
|
|
82
|
+
export declare const UPSTREAM_PRODUCT_ANALYTICS_OFF: readonly PatchOptions[];
|
|
83
|
+
/**
|
|
84
|
+
* The patches an app instance contributes to every composition: an instance that must not use the OS user's Documents folder points the chat's first
|
|
85
|
+
* workspace at its own `documents` folder. A patch for a row the surface does not compose (the terminal has no workspace controller) is ignored.
|
|
86
|
+
*/
|
|
87
|
+
export declare function instancePatches(instance: AppInstance | undefined): readonly PatchOptions[];
|
|
88
|
+
/** The profile facts a launcher hands to DSH's live configuration (stock `dsh`: `profile-boot`, `runProfile`). */
|
|
89
|
+
export declare function createProfileContext(profile: Profile, options: {
|
|
90
|
+
readonly installAnchor?: string;
|
|
91
|
+
readonly home: string;
|
|
92
|
+
readonly packageManager?: ProfileContext['packageManager'];
|
|
93
|
+
/** ACRYL's in-memory patches that a configuration reload must keep applying (see {@link acrylAdditions}). */
|
|
94
|
+
readonly overlays?: readonly PatchOptions[];
|
|
95
|
+
/** The app instance, whose own patches (see {@link instancePatches}) a reload must keep applying as well. */
|
|
96
|
+
readonly instance?: AppInstance;
|
|
97
|
+
}): ProfileContext;
|
|
98
|
+
/**
|
|
99
|
+
* The runtime resolution for a loaded profile, as stock `dsh` computes it (`profile-boot`: `composeProfile`).
|
|
100
|
+
* @param installAnchor - the `package.json` whose dependency closure the profile may import from. Defaults to the `dsh`
|
|
101
|
+
* package; a surface that ships ACRYL-owned packages (Desktop) passes its own, so those resolve like any dependency.
|
|
102
|
+
*/
|
|
103
|
+
export declare function createProfileRuntimeResolution(profile: Profile, installAnchor?: string): Promise<RuntimeResolution>;
|
|
104
|
+
/**
|
|
105
|
+
* Build the `dsh` engine definition for `createAcrylEngineHost`, bound to
|
|
106
|
+
* one profile name resolved at host-creation time (a CLI `--profile`
|
|
107
|
+
* argument, not something an engine swap changes later).
|
|
108
|
+
*/
|
|
109
|
+
export declare function createDshEngineDefinition(profileName: string, capabilities?: CodingCapabilities): AcrylEngineDefinition;
|
|
110
|
+
export declare function materializeProfilePackage(profileDir: string, packageName: string, installPackageUrl: string): void;
|
|
111
|
+
/**
|
|
112
|
+
* Resolves an ACRYL-owned workspace package by name into its live on-disk install and symlinks it into a
|
|
113
|
+
* profile, the same way the Blueprint's own fixed rows do ({@link materializeProfilePackage}) - these
|
|
114
|
+
* packages are not published, so a local extension's `package.json` cannot name one as an ordinary npm
|
|
115
|
+
* dependency. Consumed by `@acryldev/plugin-context`'s local-plugin install path (`dsh.requiresAcrylPackages`
|
|
116
|
+
* in an extension's `package.json`), which also activates the materialized package as a live Loader entry
|
|
117
|
+
* through the existing `livePluginActivation` service - this object only makes the package resolvable.
|
|
118
|
+
*/
|
|
119
|
+
export interface AcrylFrameworkPackages {
|
|
120
|
+
/** Symlink the package of module `name` (read under its current name) into `profileDir`'s `node_modules`, replacing a stale link; throws if it does not resolve from this installation. */
|
|
121
|
+
materialize(profileDir: string, name: string): void;
|
|
122
|
+
/**
|
|
123
|
+
* What a required name is today: its module, the package that module lives in, and whether a Loader row of that module is mounted
|
|
124
|
+
* and enabled now. A module inside a package (`acrylblends/cordis/router`) is not a DSH bundle of its own, so it can only be used
|
|
125
|
+
* live when it is already mounted; a plugin in the app's `plugins/` folder that declares it gets the row at the next start.
|
|
126
|
+
*/
|
|
127
|
+
describe(name: string): RequiredFrameworkModule;
|
|
128
|
+
}
|
|
129
|
+
export interface RequiredFrameworkModule {
|
|
130
|
+
readonly module: string;
|
|
131
|
+
readonly packageName: string;
|
|
132
|
+
readonly mounted: boolean;
|
|
133
|
+
}
|
|
134
|
+
declare module '@deepseek-ai/cordis' {
|
|
135
|
+
interface Context {
|
|
136
|
+
/** Resolves an ACRYL-owned workspace package by name for a local extension to depend on (see {@link AcrylFrameworkPackages}). */
|
|
137
|
+
acrylFrameworkPackages: AcrylFrameworkPackages;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* ACRYL-owned framework packages the app's own committed plugins (`<app home>/plugins/*`, `homePluginsDir`) declare
|
|
142
|
+
* through `dsh.requiresAcrylPackages` in their `package.json`. Read at compose time, not through
|
|
143
|
+
* `@acryldev/plugin-context`'s dynamic agent-runtime install path: `livePluginActivation.activate()`'s group
|
|
144
|
+
* resolution (`PluginLifecycleController`'s `bundleGroup()`, a fixed-point-free heuristic over the live Loader
|
|
145
|
+
* tree) failed a real, reproduced activation of `@acryldev/app-shell` through that path ("invalid plugin... received
|
|
146
|
+
* object") for reasons that trace into vendored Cordis internals this repo does not edit. A static row, inserted
|
|
147
|
+
* the same way the Blueprint's own fixed rows are (`composeBlueprintRows`/`materializeProfilePackage`), sidesteps
|
|
148
|
+
* dynamic activation entirely and is what every one of those fixed rows already relies on successfully.
|
|
149
|
+
* Never throws: a missing or malformed `package.json` is skipped, not fatal to boot.
|
|
150
|
+
*/
|
|
151
|
+
export declare function pluginRequiredFrameworkPackages(appHome: string): readonly string[];
|
|
152
|
+
/**
|
|
153
|
+
* The modules inside a package (`acrylblends/cordis/state`) that the plugins installed in a profile (its user bundles) declare through
|
|
154
|
+
* `dsh.requiresAcrylPackages`. A running app mounts such a module's row when one of them is installed (spec 049 T001); composing the same
|
|
155
|
+
* rows at start keeps the next start's tree what the running one had. A whole package a plugin requires is a profile bundle of its own and
|
|
156
|
+
* composes as one, so it is not listed here. Never throws: an unreadable manifest is skipped.
|
|
157
|
+
*/
|
|
158
|
+
export declare function profileRequiredFrameworkModules(profileDir: string): readonly string[];
|
|
159
|
+
/**
|
|
160
|
+
* Build the `dsh` engine definition for the Web surface's `web` profile
|
|
161
|
+
* (`dsh-base` + `dsh-web-app`) - the same shared `mountDshEngine` primitive
|
|
162
|
+
* as {@link createDshEngineDefinition}, resolved through this package's own
|
|
163
|
+
* profile system like the CLI flavor (Web has no external profile pipeline
|
|
164
|
+
* of its own, unlike Desktop's `prepareDesktopProfile()`).
|
|
165
|
+
* @param installPackageUrl - file URL of `acryl-web`'s own `package.json`,
|
|
166
|
+
* used to materialize `@acryldev/brand-client` and `@acryldev/cordis-plugin-market`
|
|
167
|
+
* into the profile (see {@link resolveWebEngineComposition}'s own comments
|
|
168
|
+
* for why that is needed).
|
|
169
|
+
*/
|
|
170
|
+
export declare function createWebEngineDefinition(installPackageUrl: string, capabilities?: CodingCapabilities): AcrylEngineDefinition;
|
|
171
|
+
/**
|
|
172
|
+
* Build the `dsh` engine definition from a composition a surface already
|
|
173
|
+
* resolved itself (Desktop's `prepareDesktopProfile()`: its own profile
|
|
174
|
+
* selection, market/editor/BLEND patch layering, and worker bare-module base
|
|
175
|
+
* URL). Performs no profile resolution of its own - unlike
|
|
176
|
+
* {@link createDshEngineDefinition}, which is the CLI/TUI flavor that
|
|
177
|
+
* resolves a profile by name through `@acryldev/harness-runtime`'s own profile
|
|
178
|
+
* system. Handing an already-resolved composition to that function would
|
|
179
|
+
* silently discard it and resolve a different profile instead.
|
|
180
|
+
*/
|
|
181
|
+
export declare function createDshEngineDefinitionFromComposition(composition: DshEngineComposition): AcrylEngineDefinition;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The file primitives ACRYL's own code writes state with, through the engine seam: an atomic replace (a reader sees the old or the new complete content,
|
|
3
|
+
* with the stated permission bits) and a cross-process writer lock (a stale holder is taken over). Today they are DeepSeek Harness's; consumers import
|
|
4
|
+
* them from `@acryldev/harness-runtime`, never from the DSH package, so replacing the implementation is a change to this file and nothing else.
|
|
5
|
+
*
|
|
6
|
+
* @module @acryldev/harness-runtime/engine-files
|
|
7
|
+
*/
|
|
8
|
+
export { withFileLock, writeFileAtomic, type FileLockOptions, type WriteFileAtomicOptions } from '@deepseek-ai/dsh-atomic-write';
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { Context } from '@deepseek-ai/cordis';
|
|
2
|
+
type CordisPlugin = Parameters<Context['plugin']>[0];
|
|
3
|
+
export interface AcrylEngineDefinition {
|
|
4
|
+
readonly id: string;
|
|
5
|
+
readonly plugin: CordisPlugin;
|
|
6
|
+
readonly config?: Record<string, unknown>;
|
|
7
|
+
}
|
|
8
|
+
export interface AcrylEngineHost {
|
|
9
|
+
readonly ctx: Context;
|
|
10
|
+
currentEngine(): string;
|
|
11
|
+
select(id: string): Promise<void>;
|
|
12
|
+
dispose(): Promise<void>;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Own the one Cordis root that selects an engine provider. Individual engines
|
|
16
|
+
* are Loader entries beneath this host, so replacing a provider keeps the host
|
|
17
|
+
* and its consumers alive while Cordis performs ordinary dependency rebinding.
|
|
18
|
+
*/
|
|
19
|
+
export declare function createAcrylEngineHost(input: {
|
|
20
|
+
readonly engines: readonly AcrylEngineDefinition[];
|
|
21
|
+
readonly initialEngine: string;
|
|
22
|
+
/**
|
|
23
|
+
* Register surface-owned services on the bare root before any engine
|
|
24
|
+
* mounts - mirrors `boot()`'s own `prepare` timing exactly (Loader is
|
|
25
|
+
* plugged, no config-tree entry has mounted yet), so a surface with its
|
|
26
|
+
* own non-engine capabilities (e.g. Desktop's profile/market/plugin-
|
|
27
|
+
* lifecycle services) can provide them ahead of an engine's Loader entries
|
|
28
|
+
* that `ctx.inject`/`ctx.get` them.
|
|
29
|
+
*/
|
|
30
|
+
readonly prepare?: (ctx: Context) => Promise<void> | void;
|
|
31
|
+
}): Promise<AcrylEngineHost>;
|
|
32
|
+
export {};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `acrylTools` provider: ACRYL's tools port (`@acryldev/control`) answered by DeepSeek Harness's tool registry today. A thin delegate: a tool defined
|
|
3
|
+
* through the port is an ordinary Harness tool (same `defineTool`, same registry), a call through `execute` runs the registry's whole pipeline, and a
|
|
4
|
+
* policy registered through `policy` is a `tools/pre-execute` hook like any other. When the registry is replaced the adapter and its consumers unload
|
|
5
|
+
* together and register again.
|
|
6
|
+
*
|
|
7
|
+
* @module @acryldev/harness-runtime/engine-tools
|
|
8
|
+
*/
|
|
9
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
10
|
+
/** Provide `acrylTools` on `ctx`, which must be able to see `tools` (call it inside `ctx.inject(['tools'], ...)`). */
|
|
11
|
+
export declare function provideAcrylTools(ctx: Context): void;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
export { ACRYL_CODING_CAPABILITIES, type AcrylCodingCapabilityDeclaration, type AcrylCodingCapabilityId, type AcrylShellMode, type AcrylSurface, } from './coding-capabilities.ts';
|
|
2
|
+
export type { CodingCapabilities } from './engine-dsh.ts';
|
|
3
|
+
export type { DurableSessionMessage, DurableSessionMessagePort, DurableSessionMessageReceipt, } from './durable-message.ts';
|
|
4
|
+
export { createAcrylSessionBridge, type AcrylSessionBridge, type AcrylSessionBridgeOptions, } from './session-bridge.ts';
|
|
5
|
+
export { installSessionLogExporter, type InstallSessionLogExporterOptions, } from './session-log-exporter.ts';
|
|
6
|
+
export { ACRYL_DEV_HOME_DIR_NAME, ACRYL_DSH_ENGINE_DIR_NAME, ACRYL_HOME_DIR_NAME, applyIsolatedDevHomeDefault, resolveAcrylDevDshHome, resolveAcrylDshHome, resolveAcrylHome, } from './acryl-home.ts';
|
|
7
|
+
export { createAcrylEngineHost, type AcrylEngineDefinition, type AcrylEngineHost, } from './engine-host.ts';
|
|
8
|
+
export { createDshEngineDefinition, createDshEngineDefinitionFromComposition, createProfileContext, createProfileRuntimeResolution, createWebEngineDefinition, pluginRequiredFrameworkPackages, profileRequiredFrameworkModules, materializeProfilePackage, UPSTREAM_PRODUCT_ANALYTICS_OFF, type AcrylFrameworkPackages, type DshEngineComposition, } from './engine-dsh.ts';
|
|
9
|
+
export { PackageOverlayNotFoundError, findOverlayPackage, packageNameFromSpecifier, resolveOverlayPackage, type PackageOverlayCandidate, type PackageOverlayOptions, type PackageOverlaySelection, type PackageOverlaySource, } from './package-overlay.ts';
|
|
10
|
+
export { installProfilePackageResolver, type InstallProfilePackageResolverOptions, } from './module-resolution.ts';
|
|
11
|
+
export { provideWebMarketInstall, WebPnpmService, WebProfilesService, type WebMarketPnpm, type WebMarketPnpmHandle, type WebMarketPnpmOutcome, type WebMarketProfile, } from './web-market-install.ts';
|
|
12
|
+
export { provideWebMarketPlugins, WebLiveActivationService, WebPluginsService, type WebMarketPluginBundle, } from './web-market-plugins.ts';
|
|
13
|
+
export { provideCliMarketInstall, CliPnpmService, CliProfilesService, type CliMarketPnpm, type CliMarketPnpmHandle, type CliMarketPnpmOutcome, type CliMarketProfile, } from './cli-market-install.ts';
|
|
14
|
+
export { provideCliMarketPlugins, CliLiveActivationService, CliPluginsService, type CliMarketPluginBundle, } from './cli-market-plugins.ts';
|
|
15
|
+
export { createAcrylPluginLifecycle, createDshPluginLifecycleHost, mountAcrylPluginLifecycle, type DshPluginLifecycleOptions, } from './plugin-lifecycle.ts';
|
|
16
|
+
export { BASE_TEMPLATE_BUNDLE_NAMES, assertProfileName, entryPatchId, isPluginLifecycleEntryId, pluginLifecyclePatches, readDisabledPluginLifecycleEntries, readUserMutableBundleNames, resolvePluginLifecycleStatePath, setPluginLifecycleEntryEnabled, type PluginLifecycleStatePersistence, type ProfileNameValidator, } from './plugin-lifecycle-state.ts';
|
|
17
|
+
export { diagnosePluginLifecycle, type PluginHealthCode, type PluginHealthFinding, type PluginHealthInput, type PluginHealthReport, type PluginHealthSeverity, } from './plugin-doctor.ts';
|
|
18
|
+
export { AcrPluginLifecycleService, PROTECTED_PLUGIN_ENTRY_REASON, PluginLifecycleError, type AcrPluginLifecycle, type AcrPluginLifecycleController, type PluginLifecycleAction, type PluginLifecycleEntryRef, type PluginLifecycleEntryView, type PluginLifecycleErrorCode, type PluginLifecycleFiberPhase, type PluginLifecycleHost, type PluginLifecycleMountedStatus, type PluginLifecycleReceipt, type PluginLifecycleSnapshot, } from '@acryldev/control';
|
|
19
|
+
import type { Context } from '@deepseek-ai/cordis';
|
|
20
|
+
import { type CodingCapabilities } from './engine-dsh.ts';
|
|
21
|
+
export interface BootAcrylHarnessProfileOptions {
|
|
22
|
+
readonly profile: string;
|
|
23
|
+
/** The surface's capability composition (`@acryldev/coding-capabilities`); without it only the profile's own rows compose. */
|
|
24
|
+
readonly capabilities?: CodingCapabilities;
|
|
25
|
+
readonly prepare?: (ctx: Context) => Promise<void> | void;
|
|
26
|
+
}
|
|
27
|
+
export interface AcrylHarnessRuntime {
|
|
28
|
+
readonly ctx: Context;
|
|
29
|
+
readonly profileDirectory: string;
|
|
30
|
+
dispose(): Promise<void>;
|
|
31
|
+
}
|
|
32
|
+
/** Boot one normal pinned-Harness ACRYL profile in a single Cordis root. */
|
|
33
|
+
export declare function bootAcrylHarnessProfile(options: BootAcrylHarnessProfileOptions): Promise<AcrylHarnessRuntime>;
|
|
34
|
+
export interface BootAcrylWebProfileOptions {
|
|
35
|
+
/** Inner arguments handed to the web-startup provider (e.g. `['--port', '4000']`). Defaults to no flags. */
|
|
36
|
+
readonly cmdlineArgs?: readonly string[];
|
|
37
|
+
/** The surface's capability composition (`@acryldev/coding-capabilities`); without it only the profile's own rows compose. */
|
|
38
|
+
readonly capabilities?: CodingCapabilities;
|
|
39
|
+
/** Host setup run after Loader installation and before any config-tree entry mounts. */
|
|
40
|
+
readonly prepare?: (ctx: Context) => Promise<void> | void;
|
|
41
|
+
}
|
|
42
|
+
export interface AcrylWebRuntime {
|
|
43
|
+
readonly ctx: Context;
|
|
44
|
+
/** The canonical bind URL, e.g. `http://127.0.0.1:3080`. */
|
|
45
|
+
readonly url: string;
|
|
46
|
+
readonly profileDirectory: string;
|
|
47
|
+
dispose(): Promise<void>;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Boot the DSH browser surface (the `web` profile: `dsh-base` + `dsh-web-app`)
|
|
51
|
+
* as one normal ACRYL runtime, so `pnpm acryl-web` serves the same DSH
|
|
52
|
+
* HTTP/WebSocket seam the web surface always uses. The shipped Web profile
|
|
53
|
+
* already owns its system prompt, agent-preset roster, and session stats, so
|
|
54
|
+
* the shared factory contributes only the missing authorization seam here.
|
|
55
|
+
*/
|
|
56
|
+
export declare function bootAcrylWebProfile(options?: BootAcrylWebProfileOptions): Promise<AcrylWebRuntime>;
|
|
57
|
+
export { captureSystemPrompt, renderSystemPromptDoc, type CaptureSystemPromptOptions, type CapturedSystemPrompt, } from './system-prompt-capture.ts';
|
|
58
|
+
export { pinnedPnpmEnv, resolvePinnedPnpm, type PinnedPnpm } from './pinned-pnpm.ts';
|
|
59
|
+
export { reconcileProfileLayout, type LayoutChange } from './profile-layout.ts';
|
|
60
|
+
export { AGENTS_BLUEPRINT, BLANK_BLUEPRINT, DSH_CHAT_ROW_IDS, DSH_PLUGIN_MANAGER_ROW_ID, PLUGIN_MANAGER_ROW_ID, IDE_BLUEPRINT, BLUEPRINT_ROW_IDS, InvalidBlueprintError, InvalidBrandIdentityError, UnknownBlueprintError, appManifest, blueprintFromManifest, catalogWithStarters, isBlendsManifest, parseBlueprint, readBlueprintFile, readStarters, blueprintFromEnvironment, brandIdentity, builtInCatalog, composeBlueprintRows, currentModule, identityLine, packageOfModule, selectBlueprint, withBrand, type Blueprint, type BlueprintBrand, type BlueprintCatalog, type BlueprintComposition, type BlueprintRowId, type BrandIdentity, } from './blueprint/index.ts';
|
|
61
|
+
export { SAFE_RECIPES, applyRepairPlan, backupsDir, createBackup, describePlan, inspectProfile, isSafeRecipe, listBackups, planRepairs, restoreBackup, undoRepair, } from './profile-repair/index.ts';
|
|
62
|
+
export type { BackupEntry, BackupManifest, InspectOptions, ProfileDiagnosis, ProfileFinding, ProfileFindingCode, RecipeId, RepairPlan, RepairResult, RepairStep, } from './profile-repair/index.ts';
|
|
63
|
+
export { WEB_PORT_ATTEMPTS, findFreeWebPort, loopbackPortIsFree, webPortPatch } from './web-port.ts';
|
|
64
|
+
export { APP_MANIFEST_FILE, APP_PLUGINS_DIR, NewAppError, planNewApp, writeNewApp, type LauncherFile, type NewAppOptions, type PlannedApp } from './app/new-app.ts';
|
|
65
|
+
export { PROFILE_OWNER_FILE, ProfileInUseError, claimProfile, type ProfileOwner } from './profile-owner.ts';
|
|
66
|
+
export { APP_DEFINITION_FILE, AppInstanceError, LockHeldError, acquireLock, announce, announceSelf, appFolder, appFolderInstance, appName, defaultInstance, developmentInstance, instanceEnvironment, IsolationRequiredError, isGitWorktree, listRunning, managedApp, ONLINE_SECRET_FILE_NAME, onlineSecretPath, osHomeDirectory, pinnedInstance, processIsAlive, profileDir, readLock, readOnlineSecret, releaseLock, removeOnlineSecret, REQUIRE_ISOLATED_HOME_ENV, runLockFileForDshHome, selectInstance, stablePort, withdraw, worktreeInstance, writeOnlineSecret, InstanceAnnounceError, type AppInstance, type AppInstanceKind, type LockHolder, type RunningApp, type SelfAnnouncement, type SelectInstanceOptions, } from './instance/index.ts';
|
|
67
|
+
export { PUBLIC_REGISTRY, StartSourceError, classifyStartSource, gitClone, resolveStartSource, type GitClone, type ResolvedStartSource, type StartSource } from './app/start-source.ts';
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A composition root's own claim and announcement (spec 048 T011). The process that serves an app takes the app's run lock and writes its Registry entry
|
|
3
|
+
* once it knows the address it really listens on, and gives both back when it exits; `acryl control list` then finds every running app, whichever launcher
|
|
4
|
+
* started it. A launcher that only spawns the app (scripts/blank.mjs, the dev runners) no longer holds the lock: the process that serves the app does, so a
|
|
5
|
+
* stop signal reaches it directly and the port in the Registry is the bound one, not the one that was asked for.
|
|
6
|
+
*
|
|
7
|
+
* @module @acryldev/harness-runtime/instance/announce-self
|
|
8
|
+
*/
|
|
9
|
+
import type { AppInstance } from './app-instance.ts';
|
|
10
|
+
/** What the running process tells the Registry about itself. */
|
|
11
|
+
export interface SelfAnnouncementInfo {
|
|
12
|
+
/** The surface serving the app: `web`, `desktop` or `cli`. */
|
|
13
|
+
readonly surface: string;
|
|
14
|
+
/** The port it is listening on, when the surface serves one. */
|
|
15
|
+
readonly port?: number;
|
|
16
|
+
/** The announcing process; defaults to this one. */
|
|
17
|
+
readonly pid?: number;
|
|
18
|
+
/** The OS user's home holding the Registry; defaults to the real one (the selector is the only reader of it). */
|
|
19
|
+
readonly osHome?: string;
|
|
20
|
+
/** How to tell whether a holder is still alive; defaults to the process table. */
|
|
21
|
+
readonly alive?: (pid: number) => boolean;
|
|
22
|
+
}
|
|
23
|
+
/** The claim and announcement this process holds, and the one call that gives them back. */
|
|
24
|
+
export interface SelfAnnouncement {
|
|
25
|
+
readonly id: string;
|
|
26
|
+
readonly port?: number;
|
|
27
|
+
/** Take the announcement and the lock back. Idempotent, and it never removes another process's claim. */
|
|
28
|
+
release(): void;
|
|
29
|
+
}
|
|
30
|
+
/** Refused because another live process already runs this app. */
|
|
31
|
+
export declare class InstanceAnnounceError extends Error {
|
|
32
|
+
constructor(message: string);
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Claim `instance` for this process and announce it, with the real port. Throws {@link InstanceAnnounceError} when a different live process already holds
|
|
36
|
+
* the app; a stale lock (its holder is gone) is taken over, as everywhere else in the instance module.
|
|
37
|
+
*/
|
|
38
|
+
export declare function announceSelf(instance: AppInstance, info: SelfAnnouncementInfo): SelfAnnouncement;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* AppInstance: everything one running ACRYL app owns on this machine, as one consistent family (spec 036, "Self-containment").
|
|
3
|
+
*
|
|
4
|
+
* Patterns, by the books in the repo's engineering rules:
|
|
5
|
+
* - **Bulkhead** (Release It!): each app is a sealed compartment; nothing it owns is reachable from another app.
|
|
6
|
+
* - **Abstract Factory** (refactoring.guru): the factories below produce a whole family of resources (home, engine home, port, Electron user data, run lock,
|
|
7
|
+
* project scope) that always belong together; a caller cannot mix one app's home with another app's port.
|
|
8
|
+
* - **Deep module / information hiding** (A Philosophy of Software Design): "where an app keeps things" is decided here and nowhere else.
|
|
9
|
+
* - The instance is chosen once, in the composition root (Clean Architecture's Main), by `select.ts`, the only code that reads the environment or the OS home.
|
|
10
|
+
*
|
|
11
|
+
* Pure: no I/O. Paths are built, never checked; `select.ts` does the few filesystem checks that choose a factory.
|
|
12
|
+
*
|
|
13
|
+
* @module @acryldev/harness-runtime/instance/app-instance
|
|
14
|
+
*/
|
|
15
|
+
/** How the instance was chosen. Only `default` may use the shared `~/.acryl`. */
|
|
16
|
+
export type AppInstanceKind = 'default' | 'development' | 'worktree' | 'app' | 'managed' | 'pinned';
|
|
17
|
+
export interface AppInstance {
|
|
18
|
+
readonly kind: AppInstanceKind;
|
|
19
|
+
/** Unique on this machine: it seeds the port, names the Electron user data and namespaces project folders. */
|
|
20
|
+
readonly id: string;
|
|
21
|
+
/** Human name (the folder name for an app). */
|
|
22
|
+
readonly name: string;
|
|
23
|
+
/** The ACRYL home: settings, sessions, profiles (under `dshHome`), global extensions, runtime state. */
|
|
24
|
+
readonly home: string;
|
|
25
|
+
/** The DSH engine home the pinned harness reads (`DSH_HOME`). */
|
|
26
|
+
readonly dshHome: string;
|
|
27
|
+
/** First Web port to try, and whether to move to the next free one when it is taken. */
|
|
28
|
+
readonly webPort: {
|
|
29
|
+
readonly start: number;
|
|
30
|
+
readonly scan: boolean;
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* Who may reach the Web server: the address it listens on (loopback unless a caller such as a container entry point asks for `0.0.0.0`) and the extra
|
|
34
|
+
* names a browser reaches it by (a proxy's public host). Non-loopback names must be listed, or DSH's connection refuses the request.
|
|
35
|
+
*/
|
|
36
|
+
readonly webAccess: WebAccess;
|
|
37
|
+
/** Electron's product name for this instance, and the name of its user-data folder before it moved into the home (read once, to carry that data over). */
|
|
38
|
+
readonly userDataName: string;
|
|
39
|
+
/**
|
|
40
|
+
* Electron's user data (window state, storage, logs, crash evidence, the single-instance lock), inside the app's own home like everything else it keeps,
|
|
41
|
+
* never in an OS application-data folder: one predictable place on every OS (`~/.acryl/desktop-data` for the installed app).
|
|
42
|
+
*/
|
|
43
|
+
readonly userDataDir: string;
|
|
44
|
+
/** Namespace for folders this app writes inside a project it opens; undefined keeps the classic shared locations. */
|
|
45
|
+
readonly projectScope?: string;
|
|
46
|
+
/**
|
|
47
|
+
* Where the chat creates its first workspace, when this app must not use the OS user's Documents folder. DSH asks the operating system for that folder
|
|
48
|
+
* (not `$HOME`), so an isolated app would otherwise write its first project into the real one. Only the default instance, which is the user's installed
|
|
49
|
+
* app, uses the OS Documents folder; every other instance keeps it inside its own home.
|
|
50
|
+
*/
|
|
51
|
+
readonly documentsDirectory?: string;
|
|
52
|
+
/** The app definition (`blend.yaml`) when this is an app folder. */
|
|
53
|
+
readonly definitionFile?: string;
|
|
54
|
+
/** The pessimistic offline lock that makes one live process per instance. */
|
|
55
|
+
readonly runLockFile: string;
|
|
56
|
+
}
|
|
57
|
+
/** See {@link AppInstance.webAccess}. */
|
|
58
|
+
export interface WebAccess {
|
|
59
|
+
readonly host: string;
|
|
60
|
+
readonly trustedHosts: readonly string[];
|
|
61
|
+
}
|
|
62
|
+
export declare const LOOPBACK_WEB_HOST = "127.0.0.1";
|
|
63
|
+
/** Bind addresses a caller may choose: loopback, or every interface (a container, where the network boundary is the container's own). */
|
|
64
|
+
export declare const WEB_HOSTS: readonly string[];
|
|
65
|
+
export declare const DEFAULT_WEB_PORT = 3080;
|
|
66
|
+
export declare const WORKTREE_WEB_PORT = 3081;
|
|
67
|
+
export declare const APP_PORT_BASE = 3100;
|
|
68
|
+
export declare const APP_PORT_SPAN = 900;
|
|
69
|
+
export declare const APP_DEFINITION_FILE = "blend.yaml";
|
|
70
|
+
export declare const RUN_LOCK_FILE = "instance.json";
|
|
71
|
+
export declare const USER_DATA_DIR_NAME = "desktop-data";
|
|
72
|
+
export declare const ENGINE_DIR_NAME = ".dsh";
|
|
73
|
+
export declare const DEFAULT_HOME_DIR_NAME = ".acryl";
|
|
74
|
+
export declare const DEVELOPMENT_HOME_DIR_NAME = ".acryl-dev";
|
|
75
|
+
export declare const WORKTREE_HOMES_DIR_NAME = ".acryl-worktrees";
|
|
76
|
+
export declare const MANAGED_HOMES_DIR_NAME = ".acryl-instances";
|
|
77
|
+
/** A project-scope id (the extension pack validates the same shape before building a path from it). */
|
|
78
|
+
export declare const PROJECT_SCOPE: RegExp;
|
|
79
|
+
export declare const PROJECT_SCOPE_MAX = 64;
|
|
80
|
+
export declare class AppInstanceError extends Error {
|
|
81
|
+
constructor(message: string);
|
|
82
|
+
}
|
|
83
|
+
/** A plain app name: lowercase letters, digits and dashes, at most 32. It becomes a folder, an app name and a port seed. */
|
|
84
|
+
export declare function appName(value: unknown): string;
|
|
85
|
+
/** FNV-1a over the id: stable across runs and platforms, spreads ids over the app port range. */
|
|
86
|
+
export declare function stablePort(id: string): number;
|
|
87
|
+
/** Plain ACRYL, nothing configured: the one instance allowed to use the shared `~/.acryl`. */
|
|
88
|
+
export declare function defaultInstance(osHome: string): AppInstance;
|
|
89
|
+
/** The isolated local development app of the main checkout (`pnpm run dev`). */
|
|
90
|
+
export declare function developmentInstance(osHome: string): AppInstance;
|
|
91
|
+
/** A second checkout (a git worktree): never the main checkout's home, port or Electron app. */
|
|
92
|
+
export declare function worktreeInstance(osHome: string, checkoutRoot: string): AppInstance;
|
|
93
|
+
/**
|
|
94
|
+
* An app folder (`acryl new`): the folder is the home. Two folders may share a name, so a folder's id carries a short digest of its real path; a managed app
|
|
95
|
+
* (kept under `~/.acryl-instances/<name>`) is unique by name.
|
|
96
|
+
*/
|
|
97
|
+
export declare function appFolderInstance(realFolder: string, managed: boolean): AppInstance;
|
|
98
|
+
/** A home a caller pinned explicitly (ACRYL_HOME without an app definition, or a legacy DSH_HOME): honoured as given. */
|
|
99
|
+
export declare function pinnedInstance(home: string, dshHome?: string): AppInstance;
|
|
100
|
+
/** The same family with an explicit port preference (ACRYL_WEB_PORT). Explicit always scans: the caller asked for a start, not a fight. */
|
|
101
|
+
export declare function withWebPort(instance: AppInstance, start: number): AppInstance;
|
|
102
|
+
/**
|
|
103
|
+
* The same family reachable beyond loopback (ACRYL_WEB_HOST, ACRYL_WEB_TRUSTED_HOSTS). The trusted names are checked again, strictly, by DSH's connection
|
|
104
|
+
* plugin at load; this only refuses what is plainly not a host name so the mistake surfaces at selection, with the variable's name.
|
|
105
|
+
*/
|
|
106
|
+
export declare function withWebAccess(instance: AppInstance, host: string, trustedHosts: readonly string[]): AppInstance;
|
|
107
|
+
/** A project-scope override (ACRYL_INSTANCE) for a pinned home. */
|
|
108
|
+
export declare function withProjectScope(instance: AppInstance, scope: string): AppInstance;
|
|
109
|
+
/**
|
|
110
|
+
* The environment contract that hands an instance to a child process or to the pinned harness. It is the ONLY way an instance crosses a process
|
|
111
|
+
* boundary: the child's `select.ts` reads these exact values back into the same family.
|
|
112
|
+
*/
|
|
113
|
+
export declare function instanceEnvironment(instance: AppInstance): Record<string, string>;
|
|
114
|
+
export declare function profileDir(instance: AppInstance, profileName: string): string;
|
|
115
|
+
/**
|
|
116
|
+
* The run lock file that owns a given engine home, for a caller that was handed a `dshHome` directly (the CLI
|
|
117
|
+
* rescue tools, `--home`) rather than a full `AppInstance`. Inverts `family()`'s default nesting
|
|
118
|
+
* (`dshHome = join(home, ENGINE_DIR_NAME)`): when `dshHome`'s last segment is `.dsh`, its app home is the parent;
|
|
119
|
+
* otherwise `dshHome` was handed in as the home itself (a pinned instance may point `dshHome` anywhere), so it is
|
|
120
|
+
* its own app home. Pure path math, no I/O: it does not choose an instance, only locates the lock file for one
|
|
121
|
+
* a caller already resolved, so it does not compete with `select.ts` for "the one place an app is chosen".
|
|
122
|
+
*/
|
|
123
|
+
export declare function runLockFileForDshHome(dshHome: string): string;
|
|
124
|
+
/** The Electron user-data name (ACRYL_LOCAL_PRODUCT_NAME): a plain folder name, never a path, so it cannot escape the user-data root. */
|
|
125
|
+
export declare function withUserDataName(instance: AppInstance, name: string): AppInstance;
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { announceSelf, InstanceAnnounceError, type SelfAnnouncement, type SelfAnnouncementInfo, } from './announce-self.ts';
|
|
2
|
+
export { APP_DEFINITION_FILE, AppInstanceError, DEFAULT_WEB_PORT, LOOPBACK_WEB_HOST, MANAGED_HOMES_DIR_NAME, PROJECT_SCOPE, PROJECT_SCOPE_MAX, RUN_LOCK_FILE, WEB_HOSTS, WORKTREE_WEB_PORT, appFolderInstance, appName, defaultInstance, developmentInstance, instanceEnvironment, pinnedInstance, profileDir, runLockFileForDshHome, stablePort, withProjectScope, withUserDataName, withWebAccess, withWebPort, worktreeInstance, type AppInstance, type AppInstanceKind, type WebAccess, } from './app-instance.ts';
|
|
3
|
+
export { LockHeldError, acquireLock, processIsAlive, readLock, releaseLock, type LockHolder } from './offline-lock.ts';
|
|
4
|
+
export { ONLINE_SECRET_FILE_NAME, onlineSecretPath, readOnlineSecret, removeOnlineSecret, writeOnlineSecret, } from './online-secret.ts';
|
|
5
|
+
export { announce, listRunning, registryDir, withdraw, type RunningApp } from './registry.ts';
|
|
6
|
+
export { IsolationRequiredError, REQUIRE_ISOLATED_HOME_ENV, appFolder, isGitWorktree, managedApp, osHomeDirectory, selectInstance, type SelectInstanceOptions } from './select.ts';
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pessimistic Offline Lock (Patterns of Enterprise Application Architecture), with the book's conditions met: ownership is visible (the file says who
|
|
3
|
+
* holds it), and a stale lock (its holder's process is gone) is taken over instead of blocking forever. Used for "one live process per app" and "one live
|
|
4
|
+
* installation per profile".
|
|
5
|
+
*
|
|
6
|
+
* @module @acryldev/harness-runtime/instance/offline-lock
|
|
7
|
+
*/
|
|
8
|
+
export interface LockHolder {
|
|
9
|
+
readonly pid: number;
|
|
10
|
+
readonly since: string;
|
|
11
|
+
readonly [detail: string]: unknown;
|
|
12
|
+
}
|
|
13
|
+
export declare class LockHeldError extends Error {
|
|
14
|
+
readonly holder: LockHolder;
|
|
15
|
+
constructor(message: string, holder: LockHolder);
|
|
16
|
+
}
|
|
17
|
+
export declare function processIsAlive(pid: number): boolean;
|
|
18
|
+
export declare function readLock(file: string): LockHolder | undefined;
|
|
19
|
+
/**
|
|
20
|
+
* Take the lock for `pid`. Refused (LockHeldError, with a message built by `describe`) when a live holder exists that `compatible` does not accept.
|
|
21
|
+
* `compatible` lets a lock admit its own kind (the same installation, the same process).
|
|
22
|
+
*/
|
|
23
|
+
export declare function acquireLock(file: string, holder: Omit<LockHolder, 'since'>, options?: {
|
|
24
|
+
readonly alive?: (pid: number) => boolean;
|
|
25
|
+
readonly compatible?: (current: LockHolder) => boolean;
|
|
26
|
+
readonly describe?: (current: LockHolder) => string;
|
|
27
|
+
}): void;
|
|
28
|
+
/** Release only our own hold: never remove a lock a newer holder took after ours went stale. */
|
|
29
|
+
export declare function releaseLock(file: string, pid?: number): void;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The online channel's per-instance secret (spec 041 TB30, following TB03's threat model): a random token
|
|
3
|
+
* written next to the instance's own run lock, readable only by the OS user that started the app (`0o600`,
|
|
4
|
+
* the same directory mode the Registry and the offline lock already use). An external CLI operator on the
|
|
5
|
+
* same machine, as the same OS user, can simply read it - no handshake, matching how Docker's own CLI trusts
|
|
6
|
+
* a local socket it can open, and how Jupyter's own token file works. A different OS user is refused by
|
|
7
|
+
* filesystem permissions alone; this adds no stronger boundary than that on purpose (TB03).
|
|
8
|
+
*
|
|
9
|
+
* Lives beside `offline-lock.ts` and `registry.ts` (not in `@acryldev/agent-control`) so both the Host plugin that
|
|
10
|
+
* writes it and the CLI that reads it depend on the same shared package, neither on the other.
|
|
11
|
+
*
|
|
12
|
+
* @module @acryldev/harness-runtime/instance/online-secret
|
|
13
|
+
*/
|
|
14
|
+
/** Plain file name, next to the run lock in the instance's own home. */
|
|
15
|
+
export declare const ONLINE_SECRET_FILE_NAME = "agent-control-secret";
|
|
16
|
+
export declare function onlineSecretPath(appHome: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* Write a fresh secret for this run. Tied to the process, not persisted across restarts (a crashed app's
|
|
19
|
+
* secret is orphaned the same way its run lock is; a fresh start writes a fresh one - TB03's rotation note).
|
|
20
|
+
* @returns the secret, hex-encoded.
|
|
21
|
+
*/
|
|
22
|
+
export declare function writeOnlineSecret(appHome: string): string;
|
|
23
|
+
/** Remove this run's secret; a caller can no longer authenticate to an instance that has shut down. */
|
|
24
|
+
export declare function removeOnlineSecret(appHome: string): void;
|
|
25
|
+
/**
|
|
26
|
+
* Read a running instance's secret (the CLI's own side, TB31): same OS user, so a plain read, no handshake.
|
|
27
|
+
* @returns the secret, or undefined when the instance has no online channel (older version, or not yet started).
|
|
28
|
+
*/
|
|
29
|
+
export declare function readOnlineSecret(appHome: string): string | undefined;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Registry (Patterns of Enterprise Application Architecture) of running apps: each running app announces itself with one small file, so `ps` finds apps
|
|
3
|
+
* wherever their folders are. An announcement whose process is gone is dropped when read. The registry lives in the OS user's `~/.acryl-instances/.running`
|
|
4
|
+
* and holds only pointers (id, folder, pid, surface, port), never app data.
|
|
5
|
+
*
|
|
6
|
+
* @module @acryldev/harness-runtime/instance/registry
|
|
7
|
+
*/
|
|
8
|
+
import { type AppInstance } from './app-instance.ts';
|
|
9
|
+
export interface RunningApp {
|
|
10
|
+
readonly id: string;
|
|
11
|
+
readonly name: string;
|
|
12
|
+
readonly home: string;
|
|
13
|
+
readonly pid: number;
|
|
14
|
+
readonly surface?: string;
|
|
15
|
+
readonly definition?: string;
|
|
16
|
+
readonly port?: number;
|
|
17
|
+
readonly since?: string;
|
|
18
|
+
}
|
|
19
|
+
export declare function registryDir(osHome: string): string;
|
|
20
|
+
export declare function announce(osHome: string, instance: AppInstance, info: {
|
|
21
|
+
readonly pid: number;
|
|
22
|
+
readonly surface?: string;
|
|
23
|
+
readonly port?: number;
|
|
24
|
+
}): void;
|
|
25
|
+
export declare function withdraw(osHome: string, instance: AppInstance, pid?: number): void;
|
|
26
|
+
export declare function listRunning(osHome: string, alive?: (pid: number) => boolean): readonly RunningApp[];
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The composition-root selector: the ONLY code in ACRYL that reads the environment or the OS home to decide where an app lives (a test enforces it).
|
|
3
|
+
* Everything else receives an `AppInstance`, or reads it from the `appInstance` Cordis service.
|
|
4
|
+
*
|
|
5
|
+
* Precedence, highest first:
|
|
6
|
+
* ACRYL_HOME with a `blend.yaml` an app folder (managed when it sits in ~/.acryl-instances)
|
|
7
|
+
* ACRYL_HOME a pinned home
|
|
8
|
+
* DSH_HOME (legacy) a pinned engine home; the ACRYL home is its parent when it is named `.dsh`
|
|
9
|
+
* checkout is a git worktree the worktree's own home
|
|
10
|
+
* development requested ~/.acryl-dev (the main checkout's `pnpm run dev`)
|
|
11
|
+
* nothing the default ~/.acryl
|
|
12
|
+
* then ACRYL_WEB_PORT (explicit start port), ACRYL_WEB_HOST and ACRYL_WEB_TRUSTED_HOSTS (reachable beyond loopback, comma-separated names), ACRYL_INSTANCE (explicit project scope) and ACRYL_LOCAL_PRODUCT_NAME (Electron user data) refine the
|
|
13
|
+
* chosen family: they are how `instanceEnvironment` hands a family to a child process.
|
|
14
|
+
*
|
|
15
|
+
* @module @acryldev/harness-runtime/instance/select
|
|
16
|
+
*/
|
|
17
|
+
import { type AppInstance } from './app-instance.ts';
|
|
18
|
+
export interface SelectInstanceOptions {
|
|
19
|
+
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
20
|
+
readonly osHome?: string;
|
|
21
|
+
/** The checkout a development launcher runs from; a git worktree gets its own instance. */
|
|
22
|
+
readonly checkout?: string;
|
|
23
|
+
/** The main checkout's isolated development app (`pnpm run dev`) rather than the default. */
|
|
24
|
+
readonly development?: boolean;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Set by a gate, a smoke or a live-run launcher: this process tree must run in an explicitly isolated home. With it set, `selectInstance` refuses (fails
|
|
28
|
+
* closed) to choose a home that is not pinned by the caller or that lies inside a real ACRYL or DSH home of the OS user, so a forgotten override ends in an
|
|
29
|
+
* error naming the fix, never in a write to the installed app's data.
|
|
30
|
+
*/
|
|
31
|
+
export declare const REQUIRE_ISOLATED_HOME_ENV = "ACRYL_REQUIRE_ISOLATED_HOME";
|
|
32
|
+
export declare class IsolationRequiredError extends Error {
|
|
33
|
+
constructor(detail: string);
|
|
34
|
+
}
|
|
35
|
+
/** Is this checkout a git worktree (its `.git` is a file pointing at the main repository)? */
|
|
36
|
+
export declare function isGitWorktree(checkoutRoot: string): boolean;
|
|
37
|
+
/** The OS user's home directory: exported only so the dev launchers need not read it themselves. */
|
|
38
|
+
export declare function osHomeDirectory(): string;
|
|
39
|
+
/** An app folder given by path (`bin/acryl`, `--dir`), whether or not it is the environment's choice. */
|
|
40
|
+
export declare function appFolder(folder: string, osHome?: string): AppInstance;
|
|
41
|
+
/** A managed app by name: `~/.acryl-instances/<name>`. */
|
|
42
|
+
export declare function managedApp(name: string, osHome?: string): AppInstance;
|
|
43
|
+
export declare function selectInstance(options?: SelectInstanceOptions): AppInstance;
|