@acrylblends/control 0.0.0-stage → 0.2.11

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 (33) hide show
  1. package/README.md +13 -2
  2. package/cordis.patch.yml +3 -0
  3. package/lib/index.js +1457 -0
  4. package/lib/index.js.map +1 -0
  5. package/lib/types/agent/agent-control.d.ts +104 -0
  6. package/lib/types/agent/providers/acp.d.ts +7 -0
  7. package/lib/types/agent/providers/capabilities.d.ts +13 -0
  8. package/lib/types/agent/providers/claude.d.ts +7 -0
  9. package/lib/types/agent/providers/codex.d.ts +7 -0
  10. package/lib/types/agent/providers/dsh-native.d.ts +7 -0
  11. package/lib/types/agent/providers/factory.d.ts +17 -0
  12. package/lib/types/agent/transports/claude-stream.d.ts +55 -0
  13. package/lib/types/architecture/projection.d.ts +43 -0
  14. package/lib/types/architecture/provider.d.ts +15 -0
  15. package/lib/types/authorization/attempts.d.ts +88 -0
  16. package/lib/types/authorization/service.d.ts +25 -0
  17. package/lib/types/authorization/types.d.ts +89 -0
  18. package/lib/types/contracts/operations.d.ts +20 -0
  19. package/lib/types/contracts/session.d.ts +42 -0
  20. package/lib/types/credential/default-model.d.ts +38 -0
  21. package/lib/types/credential/projection.d.ts +87 -0
  22. package/lib/types/credential/route-activation.d.ts +25 -0
  23. package/lib/types/credential/types.d.ts +38 -0
  24. package/lib/types/events.d.ts +14 -0
  25. package/lib/types/index.d.ts +28 -0
  26. package/lib/types/platform/tools.d.ts +113 -0
  27. package/lib/types/platform/web.d.ts +19 -0
  28. package/lib/types/plugin/controller.d.ts +145 -0
  29. package/lib/types/plugin/host.d.ts +84 -0
  30. package/lib/types/plugin/provider.d.ts +41 -0
  31. package/lib/types/plugin/types.d.ts +43 -0
  32. package/lib/types/protocol/client.d.ts +7 -0
  33. package/package.json +55 -4
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Host-neutral lifecycle authority over explicitly managed Loader entries.
3
+ *
4
+ * Every surface runs this one controller: the TUI drives it for `plugin
5
+ * enable|disable`, the Web surface mounts it through the runtime, and Desktop
6
+ * wraps it with its own projection and market bridge. The controller decides
7
+ * resolution, cascade, order, and rollback; the host port
8
+ * (`host.ts`) decides policy and persistence.
9
+ *
10
+ * @module acryl-control/plugin/controller
11
+ */
12
+ import { type Context } from '@deepseek-ai/cordis';
13
+ import { type PluginLifecycleHost } from './host.ts';
14
+ import type { PluginLifecycleMountedStatus, PluginLifecycleReceipt, PluginLifecycleSnapshot } from './types.ts';
15
+ /** Stable failures that a route, a command, or a panel may present. */
16
+ export type PluginLifecycleErrorCode = 'unknown-entry' | 'protected-entry' | 'already-enabled' | 'already-disabled' | 'not-mounted' | 'persistence-failed' | 'lifecycle-failed';
17
+ export declare class PluginLifecycleError extends Error {
18
+ readonly code: PluginLifecycleErrorCode;
19
+ constructor(code: PluginLifecycleErrorCode, message: string);
20
+ }
21
+ /** Deep module hiding Loader mutation, ordering, rollback, and cascade policy. */
22
+ export declare class AcrPluginLifecycleController {
23
+ private readonly ctx;
24
+ private readonly host;
25
+ private operation;
26
+ /**
27
+ * Entry ids this controller mounted, keyed by the package that asked for
28
+ * them. A bundle's insert row names a module specifier that need not equal
29
+ * the package name (`acryl-desktop` inserts `acryl-desktop/terminal`), and
30
+ * after an uninstall the package can no longer be asked - so what an
31
+ * activation actually created is the only authority that outlives it.
32
+ */
33
+ private readonly activatedEntries;
34
+ /**
35
+ * Module rows this controller inserted for {@link requireModules}, each with the plugin packages that need it. A row is removed when
36
+ * its last owner leaves; a row that was already mounted when a plugin asked for it is never in here, so this path never removes it.
37
+ */
38
+ private readonly moduleOwners;
39
+ constructor(ctx: Context, host: PluginLifecycleHost);
40
+ /** Project every non-group Loader entry and the host's mutation policy. */
41
+ snapshot(): PluginLifecycleSnapshot;
42
+ /**
43
+ * Apply one entry's enablement and wait until it has settled. Loader 1.0.5 (DSH 0.2) starts disposing a disabled entry's Fiber
44
+ * without waiting, and logs - rather than throws - an activation failure; a receipt must not be returned for a Fiber that is still
45
+ * unloading, and a failed activation must reach the caller so the transaction rolls back.
46
+ */
47
+ private applyEnabled;
48
+ /**
49
+ * Persist and apply one managed entry's enablement transactionally. Disabling
50
+ * an entry that mutable plugins depend on disables those dependents in the
51
+ * same transaction (dependents first, so a consumer unmounts before its
52
+ * provider); the receipt lists every id changed.
53
+ */
54
+ setEnabled(entryId: string, enabled: boolean): Promise<PluginLifecycleReceipt>;
55
+ /**
56
+ * Restart one entry, or - with no argument - the host's reload-all set:
57
+ * {@link PluginLifecycleHost.reloadAllEntryIds} when the host narrows it
58
+ * (Desktop deliberately avoids churning every market plugin's client fiber at
59
+ * once), otherwise every enabled mutable entry.
60
+ */
61
+ reload(entryId?: string): Promise<PluginLifecycleReceipt>;
62
+ /**
63
+ * Mount a just-installed profile-bundle package into the running Loader tree,
64
+ * so an install takes effect without a process restart. The bundle's row comes
65
+ * from its own cordis patch, via {@link PluginLifecycleHost.bundleRow}.
66
+ * Idempotent: a package already mounted returns its current snapshot.
67
+ *
68
+ * The host is asked for the row before the mounted-entry shortcut, so it
69
+ * stays the single authority on what may be activated at all: only it can
70
+ * tell an installed profile bundle from a package the market never managed.
71
+ */
72
+ activate(packageName: string): Promise<PluginLifecycleReceipt>;
73
+ /**
74
+ * Make the modules `owner` needs mounted (a module inside a package, such as `acrylblends/cordis/state`, which is not a profile bundle of
75
+ * its own), and release the ones it needed before and no longer names. `modules` is the owner's whole list, so an install, an update and
76
+ * an uninstall (`[]`) are the same call. A module already mounted is used as it is and never removed by this path; a missing one gets
77
+ * the row `{ id: module, name: module }`, owned by every plugin that asks for it, and removed when its last owner leaves.
78
+ *
79
+ * All or nothing: when a module cannot be mounted, the rows this call inserted are removed and the owners it added dropped before the
80
+ * error is thrown, and nothing is released; releases run only after every module is mounted. A row of the module that exists but is
81
+ * turned off is left alone and refused, because turning it off was a choice.
82
+ * @param owner - the plugin package that needs the modules.
83
+ * @param modules - every module it needs now.
84
+ */
85
+ requireModules(owner: string, modules: readonly string[]): Promise<void>;
86
+ /**
87
+ * Unmount an uninstalled package from the running Loader tree, then let the
88
+ * host prune any bookkeeping the package left behind. No-op when it is
89
+ * already gone; the host's cleanup still runs, because a package that has left
90
+ * the profile has nothing left to be disabled.
91
+ */
92
+ deactivate(packageName: string): Promise<PluginLifecycleReceipt>;
93
+ /**
94
+ * Restart the fiber of a mounted plugin identified by package name. Used by a
95
+ * local-development file watcher. No-op when the package is not mounted.
96
+ */
97
+ reloadByPackage(packageName: string): Promise<PluginLifecycleReceipt>;
98
+ /**
99
+ * Toggle a live entry by package name for a caller that knows only package
100
+ * names, not Loader ids. Resolves `false` when no live entry exists (an import
101
+ * failure, or not mounted yet), so the caller falls back to its own persisted
102
+ * state - the only mechanism that still works when a bundle's module cannot
103
+ * even be imported. Idempotent against a state that already matches, since the
104
+ * caller's own view of "current status" may be the exact stale read this
105
+ * method exists to correct.
106
+ */
107
+ setEnabledByPackageName(packageName: string, enabled: boolean): Promise<boolean>;
108
+ /**
109
+ * Read a live entry's current enabled/disabled state by package name, or
110
+ * `undefined` when it is not mounted (the caller's own persisted status is
111
+ * authoritative in that case).
112
+ */
113
+ statusOfPackage(packageName: string): PluginLifecycleMountedStatus | undefined;
114
+ private isMutable;
115
+ private protectedReason;
116
+ private reloadAllEntries;
117
+ /** Service names whose live provider is `fiber`. */
118
+ private servicesProvidedBy;
119
+ /**
120
+ * Mutable, currently-mounted entries that hard-`inject` a service `entry`
121
+ * provides and resolve it to `entry`'s fiber - transitively.
122
+ */
123
+ private mutableDependents;
124
+ private afterDeactivate;
125
+ /**
126
+ * The live entry a package occupies: the row whose module specifier is the
127
+ * package name (how a bundle row mounted by the boot Loader is identified),
128
+ * else the row this controller mounted for it. A package whose row was
129
+ * mounted at boot under a different specifier - an insert row pointing at a
130
+ * subpath - is only resolvable while the host still calls it a profile
131
+ * bundle; the activation record only covers this process.
132
+ */
133
+ private findLiveEntry;
134
+ private resolveMutable;
135
+ private receipt;
136
+ /**
137
+ * Insert one row into the profile's include group and wait until it settled; a row that did not reach ACTIVE (or PENDING) is removed
138
+ * again and its error thrown. Returns the mounted entry.
139
+ */
140
+ private mountRow;
141
+ /** Remove a row this controller inserted, wherever it sits, and wait until its Fiber has unloaded. */
142
+ private unmountRow;
143
+ /** Serialize mutations: one lifecycle transition settles before the next starts. */
144
+ private exclusive;
145
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Everything the plugin lifecycle controller needs from the host it runs in.
3
+ *
4
+ * The controller owns the lifecycle mechanics - resolution, dependent cascade,
5
+ * transaction ordering, rollback, Fiber restart - and this port supplies the
6
+ * three things that differ per surface: which entries are user-mutable, how
7
+ * enablement is persisted, and what a just-installed bundle inserts.
8
+ *
9
+ * @module acryl-control/plugin/host
10
+ */
11
+ import type { EntryGroup } from '@deepseek-ai/cordis-plugin-loader';
12
+ /** The Loader identity of one entry, as a policy sees it. */
13
+ export interface PluginLifecycleEntryRef {
14
+ /** Runtime Loader entry id, including its owning Include path when composed from one. */
15
+ readonly entryId: string;
16
+ /** Exact module specifier the entry loads. */
17
+ readonly moduleName: string;
18
+ /** Whether the entry is a Loader group rather than a plugin. */
19
+ readonly group: boolean;
20
+ }
21
+ /** The Loader row a profile-bundle package inserts, read from its own cordis patch. */
22
+ export interface PluginLifecycleBundleRow {
23
+ readonly id: string;
24
+ readonly name: string;
25
+ }
26
+ /** Shown for a non-mutable entry whose host supplies no wording of its own. */
27
+ export declare const PROTECTED_PLUGIN_ENTRY_REASON = "This entry is part of the runtime or is dependency-managed and is not user-toggleable. Plugins you add through a profile bundle or a plugin market can be enabled, disabled, and reloaded here.";
28
+ /**
29
+ * Host policy and side effects behind the lifecycle controller.
30
+ *
31
+ * Implementations are host-neutral by contract: they may read a profile, a
32
+ * state file, or a remote registry, but they never decide lifecycle order.
33
+ */
34
+ export interface PluginLifecycleHost {
35
+ /** Whether this host admits the entry to user lifecycle control. */
36
+ isMutable(entry: PluginLifecycleEntryRef): boolean;
37
+ /**
38
+ * Why an entry is not mutable, in the host's own words. Defaults to
39
+ * {@link PROTECTED_PLUGIN_ENTRY_REASON}; a surface with its own explanation
40
+ * (e.g. a Desktop runtime) overrides it.
41
+ */
42
+ protectedReason?(entry: PluginLifecycleEntryRef): string | null;
43
+ /**
44
+ * Re-read any externally derived mutation state (a bundle list a package
45
+ * manager just rewrote, for example). Called before every mutation, so a host
46
+ * does not have to keep its own view fresh.
47
+ */
48
+ refresh?(): void;
49
+ /** Persist one entry's desired enablement. Rejects when the write fails. */
50
+ setEnabled(entryId: string, enabled: boolean): Promise<void>;
51
+ /**
52
+ * The Loader row a profile-bundle package inserts, for live activation of a
53
+ * just-installed plugin. Consulted before the already-mounted shortcut, so it
54
+ * is also the host's answer to "may this package be activated at all".
55
+ *
56
+ * Throws `PluginLifecycleError` with `protected-entry` when the package is
57
+ * not an installed profile bundle, and with `lifecycle-failed` when it is a
58
+ * bundle whose patch declares no usable insert row: only the host can tell a
59
+ * package that was never installed from one that is installed but broken.
60
+ * Optional - a host without a profile-bundle concept simply does not support
61
+ * live activation.
62
+ */
63
+ bundleRow?(packageName: string): PluginLifecycleBundleRow;
64
+ /**
65
+ * The Loader group a bundle row joins. Defaults to the Loader root; a
66
+ * host that composes its profile through an include file returns that
67
+ * include's group so a live install lands among the profile's own rows.
68
+ */
69
+ bundleGroup?(): EntryGroup;
70
+ /**
71
+ * Host bookkeeping after a package leaves the Loader tree (pruning a stale
72
+ * disable record, for example). Best effort: a rejection is reported through
73
+ * {@link PluginLifecycleHost.warn} and never fails the uninstall.
74
+ */
75
+ afterDeactivate?(packageName: string): Promise<void>;
76
+ /**
77
+ * Entries "reload all" sweeps, when the host's own reload is deliberately
78
+ * narrower than every mutable entry. Optional - without it, reload-all
79
+ * restarts every enabled mutable entry.
80
+ */
81
+ reloadAllEntryIds?(): ReadonlySet<string>;
82
+ /** Reports a best-effort failure (bookkeeping cleanup) that must not throw. */
83
+ warn?(message: string): void;
84
+ }
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The Cordis service every surface injects to inspect and steer plugins.
3
+ *
4
+ * The service publishes an existing {@link AcrPluginLifecycleController} on
5
+ * `ctx.acrPluginLifecycle` for the fiber's lifetime. It takes the controller
6
+ * rather than a host because publishing a capability and building the domain
7
+ * object are different acts: a surface that also owns package-keyed
8
+ * operations (Desktop's market bridge) needs the controller itself, and both
9
+ * views must be the same object or their transitions stop sharing one queue.
10
+ *
11
+ * @module acryl-control/plugin/provider
12
+ */
13
+ import { type Context, Service } from '@deepseek-ai/cordis';
14
+ import type { AcrPluginLifecycleController } from './controller.ts';
15
+ import type { PluginLifecycleHost } from './host.ts';
16
+ import type { PluginLifecycleReceipt, PluginLifecycleSnapshot } from './types.ts';
17
+ export type { PluginLifecycleHost };
18
+ /** The resolver-facing lifecycle API: list, enable or disable, reload. */
19
+ export interface AcrPluginLifecycle {
20
+ snapshot(): PluginLifecycleSnapshot;
21
+ setEnabled(entryId: string, enabled: boolean): Promise<PluginLifecycleReceipt>;
22
+ reload(entryId?: string): Promise<PluginLifecycleReceipt>;
23
+ }
24
+ declare module '@deepseek-ai/cordis' {
25
+ interface Context {
26
+ acrPluginLifecycle: AcrPluginLifecycle;
27
+ }
28
+ }
29
+ export declare class AcrPluginLifecycleService extends Service implements AcrPluginLifecycle {
30
+ /**
31
+ * The full controller, for a host that also owns package-keyed operations
32
+ * (activating a just-installed bundle, a market's install/uninstall bridge).
33
+ * Same instance the service delegates to, so both views never drift.
34
+ */
35
+ readonly controller: AcrPluginLifecycleController;
36
+ constructor(ctx: Context, controller: AcrPluginLifecycleController);
37
+ snapshot(): PluginLifecycleSnapshot;
38
+ setEnabled(entryId: string, enabled: boolean): Promise<PluginLifecycleReceipt>;
39
+ reload(entryId?: string): Promise<PluginLifecycleReceipt>;
40
+ }
41
+ export default AcrPluginLifecycleService;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Host-neutral values for ACRYL's plugin lifecycle capability (spec 034).
3
+ *
4
+ * One lifecycle vocabulary for every surface: a TUI command, a Web settings
5
+ * panel, and the Desktop plugin tab all render these values, and the controller
6
+ * in `controller.ts` returns them. Nothing here knows about Electron, a client
7
+ * UI, a Blend, or a particular profile layout - those are host projections.
8
+ *
9
+ * @module acryl-control/plugin/types
10
+ */
11
+ /** Public Cordis Fiber phases, plus `null` for a disposed entry. */
12
+ export type PluginLifecycleFiberPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null;
13
+ export type PluginLifecycleAction = 'enable' | 'disable' | 'reload';
14
+ /** Live state of a mounted entry, as reported to a caller that knows only a package name. */
15
+ export type PluginLifecycleMountedStatus = 'active' | 'disabled';
16
+ /** One Loader entry with its current lifecycle projection. */
17
+ export interface PluginLifecycleEntryView {
18
+ readonly entryId: string;
19
+ readonly moduleName: string;
20
+ readonly enabled: boolean;
21
+ readonly hostPhase: PluginLifecycleFiberPhase;
22
+ /** Whether the host's policy admits this entry to user lifecycle control. */
23
+ readonly mutable: boolean;
24
+ /** Why this entry is not mutable; `null` when it is. */
25
+ readonly protectedReason: string | null;
26
+ /**
27
+ * Mutable, currently-mounted entries that hard-`inject` a service this entry
28
+ * provides, transitively. Disabling this entry disables them with it.
29
+ */
30
+ readonly dependents: readonly string[];
31
+ }
32
+ /** Point-in-time lifecycle projection. */
33
+ export interface PluginLifecycleSnapshot {
34
+ readonly entries: readonly PluginLifecycleEntryView[];
35
+ }
36
+ /** Result of a settled lifecycle mutation. */
37
+ export interface PluginLifecycleReceipt {
38
+ readonly accepted: true;
39
+ readonly action: PluginLifecycleAction;
40
+ /** Every entry the action changed, in application order. */
41
+ readonly entryIds: readonly string[];
42
+ readonly snapshot: PluginLifecycleSnapshot;
43
+ }
@@ -0,0 +1,7 @@
1
+ import { type AcrylSessionClient, type AcrylSessionSubscription } from '../contracts/session.ts';
2
+ export interface AcrylSessionTransport {
3
+ request(operation: string, payload: unknown): Promise<unknown>;
4
+ subscribe(operation: string, payload: unknown, listener: (value: unknown) => void, onError?: (error: Error) => void): Promise<AcrylSessionSubscription>;
5
+ }
6
+ /** Create the presentation-safe session client over an owner or attached transport. */
7
+ export declare function createAcrylSessionClient(transport: AcrylSessionTransport): AcrylSessionClient;
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@acrylblends/control",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.11",
4
+ "private": false,
5
+ "description": "Host-neutral Cordis control plane for ACRYL",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "main": "lib/index.js",
9
+ "types": "lib/types/index.d.ts",
10
+ "exports": {
11
+ ".": {
12
+ "types": "./lib/types/index.d.ts",
13
+ "default": "./lib/index.js"
14
+ },
15
+ "./package.json": "./package.json"
16
+ },
17
+ "dsh": {
18
+ "bundle": {
19
+ "patch": "./cordis.patch.yml"
20
+ }
21
+ },
22
+ "files": [
23
+ "cordis.patch.yml",
24
+ "lib/**",
25
+ "README.md"
26
+ ],
27
+ "engines": {
28
+ "node": "^22.19.0 || >=24.0.0"
29
+ },
30
+ "scripts": {
31
+ "build": "tsdown && tsc -p tsconfig.json --emitDeclarationOnly",
32
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json --noEmit",
33
+ "test": "vitest run",
34
+ "check": "pnpm run build && pnpm run typecheck && pnpm run test",
35
+ "prepack": "pnpm run check",
36
+ "prepublishOnly": "pnpm run check"
37
+ },
38
+ "peerDependencies": {
39
+ "@deepseek-ai/cordis": "^4.0.4"
40
+ },
41
+ "devDependencies": {
42
+ "@deepseek-ai/cordis": "4.0.4",
43
+ "@deepseek-ai/cordis-plugin-loader": "1.0.5",
44
+ "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
45
+ "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2",
46
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
47
+ "@deepseek-ai/dsh-session": "0.2.0-rc.2",
48
+ "@types/node": "^22.20.0",
49
+ "tsdown": "0.22.2",
50
+ "typescript": "6.0.3",
51
+ "vitest": "4.1.11"
52
+ },
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "dependencies": {}
57
+ }