@huaweidevtools/aishell-dsh-deploy 0.0.0-stage → 0.0.1-beta.3

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 (46) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +164 -2
  3. package/cordis.patch.yml +15 -0
  4. package/lib/data/permission-registry.json +1 -0
  5. package/lib/data/terraform-examples.zip +0 -0
  6. package/lib/index.js +4796 -0
  7. package/lib/types/auth-http.d.ts +44 -0
  8. package/lib/types/auth-obs-signer.d.ts +46 -0
  9. package/lib/types/auth-signer.d.ts +46 -0
  10. package/lib/types/bridge.d.ts +70 -0
  11. package/lib/types/credentials.d.ts +105 -0
  12. package/lib/types/data-paths.d.ts +70 -0
  13. package/lib/types/deployment-state.d.ts +69 -0
  14. package/lib/types/gates/cost_gate.d.ts +24 -0
  15. package/lib/types/gates/credential_gate.d.ts +21 -0
  16. package/lib/types/gates/mirror.d.ts +27 -0
  17. package/lib/types/gates/networking_gate.d.ts +9 -0
  18. package/lib/types/gates/terraform_env.d.ts +26 -0
  19. package/lib/types/index.d.ts +96 -0
  20. package/lib/types/permission/gate.d.ts +87 -0
  21. package/lib/types/permission/mode.d.ts +69 -0
  22. package/lib/types/permission/registry.d.ts +109 -0
  23. package/lib/types/permission-context.d.ts +84 -0
  24. package/lib/types/permission-route.d.ts +78 -0
  25. package/lib/types/permission.d.ts +37 -0
  26. package/lib/types/prompt.d.ts +59 -0
  27. package/lib/types/schemas/cost.d.ts +108 -0
  28. package/lib/types/schemas/networking.d.ts +115 -0
  29. package/lib/types/security-groups.d.ts +43 -0
  30. package/lib/types/tools/annotations.d.ts +94 -0
  31. package/lib/types/tools/balance_summary.d.ts +69 -0
  32. package/lib/types/tools/cost.d.ts +16 -0
  33. package/lib/types/tools/deployment.d.ts +14 -0
  34. package/lib/types/tools/errors.d.ts +40 -0
  35. package/lib/types/tools/examples.d.ts +4 -0
  36. package/lib/types/tools/existing_resources.d.ts +29 -0
  37. package/lib/types/tools/index.d.ts +32 -0
  38. package/lib/types/tools/networking.d.ts +13 -0
  39. package/lib/types/tools/openapi.d.ts +113 -0
  40. package/lib/types/tools/provider_schema.d.ts +19 -0
  41. package/lib/types/tools/terraform.d.ts +32 -0
  42. package/lib/types/types.d.ts +84 -0
  43. package/lib/types/utils/hash.d.ts +11 -0
  44. package/lib/types/utils/tar.d.ts +29 -0
  45. package/lib/types/version.d.ts +18 -0
  46. package/package.json +59 -3
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Enforcement for read-only mode — the two gates.
3
+ *
4
+ * Read-only mode is enforced at two levels, because the tools reach
5
+ * HuaweiCloud through two paths that do not share an entry point.
6
+ *
7
+ * ## Gate 1 — the signed-HTTP funnel
8
+ *
9
+ * Every signed request to a HuaweiCloud endpoint goes through `signedHttp`
10
+ * (`openapi_request`, `existing_resources`, `balance_summary`, `apiexplorer`).
11
+ * Checking there covers every cloud call the agent can compose itself,
12
+ * including the arbitrary method/URL that `openapi_request` accepts, without
13
+ * each tool having to remember to ask.
14
+ *
15
+ * IAM credential verification used to be one of those callers. It moved to the
16
+ * shared `credentials-store/verify` module when `auth` moved to
17
+ * `aishell-credentials`, so it is no longer gated here — correctly: verifying a
18
+ * credential the person just supplied is not a cloud mutation, and a session
19
+ * in read-only mode must still be able to answer "are these credentials
20
+ * valid?" before anything is planned.
21
+ *
22
+ * The check applies to every call, including any that pass credentials
23
+ * explicitly. Keying an exemption on whether a caller happened to pass a
24
+ * parameter would leave a back door that opens for any future caller of any
25
+ * method.
26
+ *
27
+ * ## Gate 2 — the tool registry
28
+ *
29
+ * The terraform tools shell out to the `terraform` binary and never touch
30
+ * `signedHttp`, so gate 1 cannot see them. Two of them change cloud state:
31
+ *
32
+ * - `terraform_apply` creates and modifies resources.
33
+ * - `terraform_destroy` deletes them.
34
+ *
35
+ * Everything else in that family only reads or writes local files —
36
+ * `plan`, `init`, `refresh`, `import`, `state`, `install`, `provider_schema`,
37
+ * `terraform_examples_export` — and stays available, so a read-only session
38
+ * can still show a user what a change *would* do. Refusing `plan` would make
39
+ * read-only mode useless for its main purpose: reviewing before approving.
40
+ *
41
+ * ## What this does not cover
42
+ *
43
+ * These gates protect cloud resources. They are not a sandbox: a terraform run
44
+ * writes files, downloads providers, and spawns processes, and none of that is
45
+ * gated. `terraform_plan` can still write a state file, and `terraform_import`
46
+ * can still modify local state. That is by design — the promise is "will not
47
+ * change your cloud account", and it is stated that way to users rather than
48
+ * as a blanket "read-only".
49
+ *
50
+ * @module permission/gate
51
+ */
52
+ /**
53
+ * Tools that change cloud state without going through `signedHttp`.
54
+ *
55
+ * Anything reached by `signedHttp` is covered by gate 1 and must NOT be listed
56
+ * here — listing it would refuse reads that gate 1 already admits. A new tool
57
+ * that mutates cloud state by some other route (a new binary, a direct fetch)
58
+ * must be added.
59
+ */
60
+ export declare const CLOUD_MUTATING_TOOLS: ReadonlySet<string>;
61
+ /**
62
+ * A refusal from the read-only gate.
63
+ *
64
+ * Its own type so callers can tell a policy decision from a transport failure:
65
+ * tool code that wraps errors would otherwise report a refusal as
66
+ * "request failed", which reads like a bug rather than a rule. `openapi.ts`
67
+ * checks for this and returns the message verbatim.
68
+ */
69
+ export declare class PermissionRefusalError extends Error {
70
+ readonly name = "PermissionRefusalError";
71
+ }
72
+ /**
73
+ * Check a tool call against read-only mode.
74
+ *
75
+ * @param toolName - the tool about to run.
76
+ * @returns a message to return as a failed tool result, or `undefined` to proceed.
77
+ */
78
+ export declare function denyTool(toolName: string): string | undefined;
79
+ /**
80
+ * Check a signed HTTP request against read-only mode.
81
+ *
82
+ * @param method - HTTP method.
83
+ * @param url - the full request URL.
84
+ * @returns a message describing the refusal, or `undefined` to proceed.
85
+ */
86
+ export declare function denyHttp(method: string, url: URL): string | undefined;
87
+ //# sourceMappingURL=gate.d.ts.map
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Approval mode — the out-of-band read-only / read-write switch.
3
+ *
4
+ * ## What this gates
5
+ *
6
+ * Read-only mode protects **HuaweiCloud resources**: it stops the agent from
7
+ * creating, modifying, or deleting anything in the account. It is not a
8
+ * sandbox. Operations with no cloud effect — a terraform binary run, a plan
9
+ * file written to disk, a local command — are outside what this switch can
10
+ * see, and are not claimed to be covered.
11
+ *
12
+ * ## Why the mode lives here and not in the conversation
13
+ *
14
+ * The switch is out-of-band: a human flips it in the client UI, which reaches
15
+ * this process over the authenticated Host route (`../permission-route.ts`), and
16
+ * this module's memory changes.
17
+ *
18
+ * The mode is not an exposed surface: it appears in no tool description, no
19
+ * tool result, and no `tools/list` entry, and no tool sets it. An agent cannot
20
+ * read it on demand, and cannot argue its way into write access.
21
+ *
22
+ * A denial, however, does reveal the current state — `denyTool` and `denyHttp`
23
+ * name read-only mode in the message they return. That is deliberate, and it
24
+ * is not closable by wording: were the session in read-write the request would
25
+ * not be refused at all, so the mere fact of refusal carries the same one bit
26
+ * whatever the text says. A refusal that explained nothing would only make the
27
+ * model retry and leave the user without a remedy. The state is one-way
28
+ * observable at the moment it blocks you, and one-way unchangeable — which is
29
+ * the property that matters.
30
+ *
31
+ * The mode is deliberately not persisted. A restart returns to the default,
32
+ * so a session that needs write access must be granted it again — the safe
33
+ * direction to fail.
34
+ *
35
+ * @module permission/mode
36
+ */
37
+ /** Whether mutations are permitted. */
38
+ export type PermissionMode = "read_only" | "read_write";
39
+ /**
40
+ * Parse a mode string.
41
+ *
42
+ * Accepts the wire spellings plus a few the operator is likely to type in an
43
+ * environment variable. Anything unrecognised yields `undefined` rather than
44
+ * throwing, so a typo degrades to the default instead of failing startup.
45
+ *
46
+ * @param value - candidate string.
47
+ * @returns the mode, or `undefined` when unrecognised.
48
+ */
49
+ export declare function parseMode(value: string | undefined): PermissionMode | undefined;
50
+ /** The mode in effect. */
51
+ export declare function getMode(): PermissionMode;
52
+ /**
53
+ * Set the mode.
54
+ *
55
+ * @param mode - the mode to apply.
56
+ * @returns the previous mode, for a change log.
57
+ */
58
+ export declare function setMode(mode: PermissionMode): PermissionMode;
59
+ /** Whether mutations are currently permitted. */
60
+ export declare function writesAllowed(): boolean;
61
+ /**
62
+ * Reset to the startup default.
63
+ *
64
+ * Used by tests, which must not leak a mode change into the next case.
65
+ */
66
+ export declare function resetMode(): void;
67
+ /** Startup default, for logging and for `permission/get_mode`. */
68
+ export declare function defaultMode(): PermissionMode;
69
+ //# sourceMappingURL=mode.d.ts.map
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Read-only registry — answers "is this request a query?" for arbitrary URLs.
3
+ *
4
+ * `openapi_request` takes a method and a URL straight from the model, so the
5
+ * only way to know whether a call mutates cloud state is to look the URL up
6
+ * in a table built from the API catalog. This module owns that lookup.
7
+ *
8
+ * ## The decision
9
+ *
10
+ * {@link isReadOnlyPermitted} returns true when a request may proceed in
11
+ * read-only mode. Its rules, in order:
12
+ *
13
+ * - `GET` and `HEAD` are queries. No lookup. HTTP defines them as safe
14
+ * methods, and the metadata does not cover every service reachable here
15
+ * reach — OBS has no entry at all, so a lookup would deny an object
16
+ * download. Method alone gets OBS right: its reads are GET, its mutations
17
+ * are PUT/POST/DELETE.
18
+ * - Anything else is looked up in the registry, keyed by method and the
19
+ * host's first label. A match means the operation is a known query.
20
+ * - No match means deny. The default is deny, so an operation the registry
21
+ * has never heard of — a new API, a service that is not in the catalog, a
22
+ * typo — cannot become a permitted mutation.
23
+ *
24
+ * The asymmetry is the point: a false deny costs one rejected query, which
25
+ * the operator can see and fix; a false permit is an unasked-for change to
26
+ * production infrastructure.
27
+ *
28
+ * ## Known coverage gap: the table covers less than the catalog
29
+ *
30
+ * The registry is built from the hcloud CLI's cached APIExplorer metadata. That
31
+ * cache is not the whole catalog. Measured 2026-10-07 by calling
32
+ * `ListProductsV4` / `ListApis` on `apiexplorer.cn-north-4.myhuaweicloud.com`:
33
+ *
34
+ * APIExplorer catalog 310 products, 221 with a non-zero api_count
35
+ * api_count totals 18,693
36
+ * hcloud cache 129 services, 11,439 API files
37
+ * not in the cache 92 products, 5,789 APIs
38
+ *
39
+ * The bulk of the shortfall is HCS and ManageOne services (Huawei Cloud Stack),
40
+ * which are not public-cloud services. The rest is public: IDT (930 APIs),
41
+ * MetaStudio (293), AgentArts (247), eiHealth (223), WorkspaceApp (174),
42
+ * IEF (111), OBS (94 by the catalog's count), and others.
43
+ *
44
+ * Consequence: for a service absent from the table, every non-GET/HEAD request
45
+ * is refused in read-only mode, including reads that would be safe. The
46
+ * direction is the intended one — a legitimate query is rejected rather than a
47
+ * mutation admitted — so the cost is user-visible friction, not exposure.
48
+ *
49
+ * OBS deserves separate mention because its case is different. The catalog
50
+ * lists it with 94 APIs, but `ListApis?productshort=OBS` returns zero entries,
51
+ * so there is no per-operation metadata to build patterns from regardless of
52
+ * what else is fetched. OBS is the one service the GET/HEAD rule carries
53
+ * entirely on its own.
54
+ *
55
+ * The cache was written as a single batch (all 129 directories share one
56
+ * mtime), and the catalog figures above come from live APIExplorer responses,
57
+ * not from the cache. A burst of `ListApis` calls during measurement returned
58
+ * HTTP 429.
59
+ *
60
+ * ## Why the host's first label is the service key
61
+ *
62
+ * The service directory in the metadata is not recoverable from a request —
63
+ * only method and URL are. Host labels are also coarser than directories, and
64
+ * several directories share one label (`kafka`, `rabbitmq`, and `rocketmq` all
65
+ * serve from `dms.*`; `eip` serves from `vpc.*`). Keying on the label is both
66
+ * derivable and safer: those services collapse into one bucket, so a path
67
+ * segment they share can never be resolved to the wrong one.
68
+ *
69
+ * ## Loading
70
+ *
71
+ * The artifact is read once, lazily, on the first lookup, and cached for the
72
+ * process lifetime. Patterns are compiled once at load. A missing or
73
+ * unreadable artifact does not break the tools: the registry reports itself
74
+ * unavailable and every non-GET/HEAD request is denied — read-only mode fails
75
+ * closed rather than silently permitting writes.
76
+ *
77
+ * @module permission/registry
78
+ */
79
+ /** Why a request was permitted or denied. */
80
+ export type Decision = {
81
+ readonly allowed: true;
82
+ readonly reason: "safe-method" | "registry-match";
83
+ } | {
84
+ readonly allowed: false;
85
+ readonly reason: "registry-miss" | "registry-unavailable";
86
+ };
87
+ /**
88
+ * Decide whether a request may proceed in read-only mode.
89
+ *
90
+ * @param method - HTTP method, any case.
91
+ * @param url - the full request URL.
92
+ * @returns the decision, with the reason for it.
93
+ */
94
+ export declare function isReadOnlyPermitted(method: string, url: URL): Decision;
95
+ /**
96
+ * Whether the registry loaded successfully.
97
+ *
98
+ * Reported once at startup so an operator learns immediately that read-only
99
+ * mode is denying everything, rather than discovering it from a tool result.
100
+ *
101
+ * @returns `undefined` when healthy, otherwise the load failure.
102
+ */
103
+ export declare function registryStatus(): {
104
+ readonly patterns: number;
105
+ readonly error?: string;
106
+ };
107
+ /** Drop the cache so the next lookup reloads. Used by tests. */
108
+ export declare function resetRegistry(): void;
109
+ //# sourceMappingURL=registry.d.ts.map
@@ -0,0 +1,84 @@
1
+ /**
2
+ * The read-only policy, as guidance the model reads before it acts.
3
+ *
4
+ * ## Why a runtime context and not a prompt section
5
+ *
6
+ * `systemPrompt.context()` materializes as a separate history message and is
7
+ * committed only when its text changes. `systemPrompt.section()` would edit the
8
+ * system prompt itself, so flipping the switch would invalidate the cache from
9
+ * the first token on every turn. The mode is stable for most turns, so the
10
+ * context costs one short message when it changes and nothing afterwards.
11
+ *
12
+ * The order is the approval policy's, because this is the same kind of fact: an
13
+ * out-of-band decision the model must work under rather than one it made.
14
+ *
15
+ * ## What this text is, and is not
16
+ *
17
+ * The mode is enforced by this plugin's own gate: it refuses cloud
18
+ * mutations at the tool and HTTP layers, and it names the specific operation
19
+ * and what remains available when it does. That gate is the guarantee — a
20
+ * refusal cannot be talked around.
21
+ *
22
+ * This text therefore does not restate the gate's rules. It covers what the
23
+ * gate cannot: the way of working. A read-only session is a review session, and
24
+ * the model should carry the work through rather than decline it. The
25
+ * over-refusal it guards against is the default failure of a prompt-side
26
+ * constraint: a model that reads "read-only" as "I may not touch anything",
27
+ * stops early, and leaves the user with less than they asked for.
28
+ *
29
+ * ## The gap this text cannot close
30
+ *
31
+ * The gate covers the paths this plugin owns — its tools and the signed
32
+ * HTTP requests they make. A cloud resource reachable another way (an
33
+ * EIP, a tunnel, an internal address) is the same account over a route no
34
+ * permission check here sees, and nothing in this plugin can intercept a local
35
+ * shell command to stop it. So the reachable-route paragraph is the only
36
+ * constraint on that path, and it is an instruction rather than an enforcement.
37
+ * Closing it for real is a network-layer decision — leaving the resource
38
+ * unreachable — not something a plugin can do.
39
+ *
40
+ * @module @huaweidevtools/aishell-dsh-deploy/permission-context
41
+ */
42
+ import type { Context } from '@deepseek-ai/cordis';
43
+ import type { PermissionMode } from './permission.ts';
44
+ /** Name this contribution registers under; unique across the assembled prompt. */
45
+ export declare const PERMISSION_CONTEXT_NAME = "aishell:permission-policy";
46
+ /**
47
+ * What the model reads while mutations are refused.
48
+ *
49
+ * Three paragraphs, each doing one job: the state and its scope, the route
50
+ * the gate does not cover, and the way of working that keeps a read-only
51
+ * session useful.
52
+ */
53
+ export declare const READ_ONLY_POLICY = "Current HuaweiCloud permission mode: read-only \u2014 nothing in the HuaweiCloud account is to change, by any route, including resources reachable directly.\n\nAn EIP, a tunnel, or an internal address that answers is still the same account. Reads over such a path are fine; state changes are not. Reaching a resource by a route the permission check does not cover does not make the change allowed \u2014 do not use one to do what a refusal declined.\n\nLocal work is unaffected: files and local processes are yours. Treat the session as review work \u2014 carry the investigation through and produce the complete change (plan, exact commands, cost or impact), stating what would be applied. Ask for read-write only when a specific operation is blocked.";
54
+ /**
55
+ * The text this context contributes for one mode.
56
+ *
57
+ * Read-write contributes nothing, and that is the whole point: `''` drops the
58
+ * contribution from the snapshot, so there is no "you may now write" line to
59
+ * go stale. Only read-only needs saying.
60
+ *
61
+ * An unknown mode contributes nothing either. Before the first read lands the
62
+ * mode is genuinely unknown, and announcing read-only then would state a
63
+ * restriction that may not hold — while the gate, if it is in fact read-only,
64
+ * refuses precisely anyway.
65
+ *
66
+ * @param mode - the mode now in effect, or `undefined` before one is read.
67
+ * @returns the policy text, or `''` to contribute nothing.
68
+ */
69
+ export declare function permissionPolicyText(mode: PermissionMode | undefined): string;
70
+ /**
71
+ * Register the policy context, reading the mode through `current` at each
72
+ * assembly.
73
+ *
74
+ * Deferred behind `ctx.inject` rather than declared in this plugin's own
75
+ * `inject`: the policy is an enhancement, and a deployment without the system
76
+ * prompt should not lose the tools over it. `current` is a function because the
77
+ * context provider is synchronous and evaluated per assembly, so the mode is
78
+ * read from the module state at that moment rather than captured once.
79
+ *
80
+ * @param ctx - host context.
81
+ * @param current - the mode last read or applied, or `undefined` if not yet read.
82
+ */
83
+ export declare function registerPermissionPolicyContext(ctx: Context, current: () => PermissionMode | undefined): void;
84
+ //# sourceMappingURL=permission-context.d.ts.map
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Host route for the permission mode switch.
3
+ *
4
+ * The composer chip lives in the browser and the mode lives in this process.
5
+ * A settings document cannot carry that toggle — it is out-of-band state the
6
+ * model must neither see nor set — so this route carries it the same way the
7
+ * credential route carries secrets: an authenticated browser-to-host HTTP
8
+ * round trip.
9
+ *
10
+ * `GET api/aishell/permission` -> current mode
11
+ * `POST api/aishell/permission` <- { mode } -> the applied change
12
+ *
13
+ * ## How the mode is reached
14
+ *
15
+ * The deps are two functions over this plugin's own module state, so a switch
16
+ * takes effect before the next tool call starts rather than after a round
17
+ * trip.
18
+ *
19
+ * ## Errors are reported, not thrown
20
+ *
21
+ * The route answers 200 with `{ ok: false, error }` so the chip can show the
22
+ * message. Only a malformed request earns a 4xx. The two remaining failure
23
+ * modes are both malformed input, so `ok: false` now covers request validation
24
+ * only — but the envelope is unchanged, because the client half already
25
+ * renders it and a shape change would be a second thing to keep in step.
26
+ *
27
+ * @module @huaweidevtools/aishell-dsh-deploy/permission-route
28
+ */
29
+ import { type PermissionMode, type PermissionModeState, type PermissionModeChange } from './permission.ts';
30
+ /** Route path, mounted under the host's authenticated `/api` fence. */
31
+ export declare const PERMISSION_PATH = "/api/aishell/permission";
32
+ /** What this route needs: the plugin's own mode state. */
33
+ export interface PermissionRouteDeps {
34
+ /** Read the mode now in effect, with the startup default and writability. */
35
+ readonly read: () => PermissionModeState;
36
+ /** Apply a mode; returns the change so the browser can render it. */
37
+ readonly write: (mode: PermissionMode) => PermissionModeChange;
38
+ }
39
+ /** A successful response: the mode now in effect. */
40
+ export interface PermissionStatus extends PermissionModeState {
41
+ readonly ok: true;
42
+ }
43
+ /**
44
+ * A failed response.
45
+ *
46
+ * Still carries no `mode`, `default`, or `writable`. Validation failures are
47
+ * the only remaining source, but the rule stays: a request that could not be
48
+ * answered must not be answered with a guess.
49
+ */
50
+ export interface PermissionFailure {
51
+ readonly ok: false;
52
+ /** Human-readable reason; rendered by the client's form. */
53
+ readonly error: string;
54
+ }
55
+ /**
56
+ * Report the current mode.
57
+ *
58
+ * @param deps - route collaborators.
59
+ */
60
+ export declare function getMode(deps: PermissionRouteDeps): Promise<Response>;
61
+ /**
62
+ * Apply a mode.
63
+ *
64
+ * @param deps - route collaborators.
65
+ * @param request - the incoming POST; its body carries `{ mode }`.
66
+ */
67
+ export declare function setMode(deps: PermissionRouteDeps, request: Request): Promise<Response>;
68
+ /**
69
+ * Build the route handlers.
70
+ *
71
+ * @param deps - route collaborators.
72
+ * @returns handlers for the fetch registry.
73
+ */
74
+ export declare function createPermissionRoutes(deps: PermissionRouteDeps): {
75
+ get: () => Promise<Response>;
76
+ set: (request: Request) => Promise<Response>;
77
+ };
78
+ //# sourceMappingURL=permission-route.d.ts.map
@@ -0,0 +1,37 @@
1
+ /**
2
+ * The permission mode vocabulary the route and the prompt share.
3
+ *
4
+ * The mode itself lives in `./permission/mode.ts`, next to the gate that
5
+ * enforces it — the tools read it directly (`writesAllowed()`, `getMode()`), so
6
+ * there is no client half to write and no request to make.
7
+ *
8
+ * What stays here is the *wire* vocabulary: the two spellings the browser sends
9
+ * and the shapes the route answers with. Declared separately from the internal
10
+ * module rather than imported from it, so a change to the module's internal
11
+ * naming cannot silently change the wire.
12
+ *
13
+ * @module @huaweidevtools/aishell-dsh-deploy/permission
14
+ */
15
+ /** The two modes, spelled as the browser sends them. */
16
+ export declare const PERMISSION_MODES: readonly ["read_only", "read_write"];
17
+ /** One permission mode. */
18
+ export type PermissionMode = (typeof PERMISSION_MODES)[number];
19
+ /** Result of `GET api/aishell/permission`. */
20
+ export interface PermissionModeState {
21
+ /** Mode now in effect. */
22
+ readonly mode: PermissionMode;
23
+ /** Mode this process started in. */
24
+ readonly default: PermissionMode;
25
+ /** Whether mutations are currently permitted. */
26
+ readonly writable: boolean;
27
+ }
28
+ /** Result of `POST api/aishell/permission`. */
29
+ export interface PermissionModeChange {
30
+ /** Mode now in effect. */
31
+ readonly mode: PermissionMode;
32
+ /** Mode before the call. */
33
+ readonly previous: PermissionMode;
34
+ /** Whether the mode actually changed. */
35
+ readonly changed: boolean;
36
+ }
37
+ //# sourceMappingURL=permission.d.ts.map
@@ -0,0 +1,59 @@
1
+ /**
2
+ * What the model reads about how to use this plugin's tools.
3
+ *
4
+ * ## Why a prompt section and not just tool descriptions
5
+ *
6
+ * Seventeen tools each say what they do. None of them says what *order* to
7
+ * call them in, or where a person has to approve before the next step runs.
8
+ * That knowledge is the difference between a model that can drive a deployment
9
+ * and one that calls `terraform_apply` on a directory with no `networking.json`
10
+ * and no cost estimate, then reports the resulting gate refusal as a bug.
11
+ *
12
+ * The section also carries the constraint the tools cannot express: several
13
+ * steps require explicit user consent before proceeding, and a tool description
14
+ * is the wrong place to say so — the model reads descriptions once while
15
+ * deciding which tool to call, not at the moment it is about to act.
16
+ *
17
+ * ## Why `section()` and not `context()`
18
+ *
19
+ * The policy switch uses `context()`, because a mode change should cost one
20
+ * message when it changes and nothing afterwards. This text is different: it is
21
+ * stable, and it must be present on every turn, not committed once as history.
22
+ * A section is part of the assembled prompt, so it is in front of the model at
23
+ * every step.
24
+ *
25
+ * ## Order
26
+ *
27
+ * `MCP_SERVERS` (3100) — after every built-in tool section, before `TOOLS_SDK`.
28
+ * That is where the assembled prompt places server-contributed tool guidance,
29
+ * and this is exactly that: guidance for a group of contributed tools. A number
30
+ * rather than a name is not needed here; the table has a slot for it.
31
+ *
32
+ * @module @huaweidevtools/aishell-dsh-deploy/prompt
33
+ */
34
+ import type { Context } from '@deepseek-ai/cordis';
35
+ /** Name this contribution registers under; unique across the assembled prompt. */
36
+ export declare const WORKFLOW_SECTION_NAME = "aishell:deploy-workflow";
37
+ /**
38
+ * What the model reads.
39
+ *
40
+ * Written in English like every other host-side string in this repo — prompt
41
+ * sections are host text, and the browser half owns localized copy. The model
42
+ * relays the answer in the user's language; the instructions do not need to
43
+ * change language to do that.
44
+ *
45
+ * Every tool name appears as the model sees it, `aishell__<name>`, so a model
46
+ * can copy it straight into a call.
47
+ */
48
+ export declare const DEPLOY_WORKFLOW = "Huawei Cloud work goes through the aishell__ tools below, not through shell commands. They carry the safety gates (a plaintext-credential scan, a cost-hash check, a networking check) that a bare `terraform` invocation bypasses.\n\n## Deployment flow\n\nSteps marked \u2605 require the user's explicit agreement before you continue.\n\n1. aishell__auth \u2014 verify the account and list its projects. Each project's `name` is a region; a region-scoped API (one whose path contains `{project_id}`) needs the project id from here.\n2. aishell__create_deployment \u2014 create or reuse the deployment workspace.\n3. aishell__apiexplorer \u2014 look up API definitions. With no arguments it lists every service; with a product it lists that service's APIs; with an API name it returns the contract (`compact: true` for the condensed form, `regions: true` for available regions and project ids).\n aishell__terraform_examples_export \u2014 write `.tf` examples to a directory. That directory is a reference target, not the deployment workspace.\n4. aishell__update_networking \u2014 design the topology: VPC, subnets, routes, security groups, plus the EIP/NAT/ELB objects and the component list.\n \u2605 Show the topology to the user and get explicit agreement before writing it. Include VPC, subnet CIDRs, security-group rules and how the network objects connect; prefer rendering it as HTML. If the user asks for changes, revise until they accept, then call the tool again. Do not start any later step before that.\n \u2605 Opening SSH to 0.0.0.0/0 is a risk. Tell the user to restrict the source range.\n5. aishell__list_existing_resources \u2014 inventory what already exists that could be reused. The response also carries a balance summary (balance and vouchers).\n6. Decide per component: reuse or create.\n - Reuse: the spec and charging are fixed by the existing resource. Write the resource block, then aishell__terraform_import to bring it into state.\n - Create: choose a spec and a charging mode, querying available flavors and images with aishell__openapi_request.\n7. aishell__openapi_request(\"GET\", <BSS price API>) \u2014 fetch the real price for the new resources. Use the `fields` parameter to keep large responses out of context.\n8. aishell__update_cost \u2014 write `cost.json`: spec, charging, price, and whether each item is reused or new.\n \u2605 Show the cost breakdown before continuing: what is reused, what is bought, each item's spec and charging mode, and the new monthly total.\n9. Report the balance summary from step 5: balance and vouchers. Vouchers are applied automatically at the account level (voucher, then cash coupon, then balance) with nothing to configure in `.tf`. If vouchers exist, say the actual monthly increase may come in below the `cost.json` estimate. Check each voucher's `expire_time` and warn about any nearing expiry.\n10. Write the `.tf` files from `cost.json` and `networking.json`. Credentials come from the environment; never write `access_key`, `secret_key` or `security_token` into a `.tf` file.\n11. aishell__terraform_init \u2014 the gate here scans for plaintext credentials and refuses if it finds any.\n12. aishell__provider_schema \u2014 the argument contract for a resource type, when you need it.\n13. aishell__terraform_plan \u2014 preview the change.\n \u2605 Show the plan summary (what will be created, changed and destroyed) and the security-group rules before applying.\n14. aishell__terraform_apply \u2014 run it. Four gates run first: `networking.json` exists, `cost.json` exists, its `tf_hash` still matches the `.tf` files, and no plaintext credential is present.\n\n## Destroying and resynchronising\n\n- aishell__terraform_destroy removes everything terraform manages in that deployment. It refuses a non-empty tfstate only after the credential scan passes.\n \u2605 List the resources that will be destroyed and get explicit agreement first. Destruction cannot be undone.\n If the deployment also imported existing resources, destroy only what this deployment created with `target: [...]` and leave the imported ones. Call aishell__terraform_state first to list the addresses and let the user choose.\n- aishell__terraform_refresh \u2014 when the cloud changed outside terraform (edited in the console, a resource deleted by hand), refresh state and then plan to see the difference.\n- aishell__terraform_state \u2014 read state: resource addresses, attributes, security-group rules.\n\n## Hard lines\n\n- Cloud resources are created and destroyed **only** through aishell__terraform_apply and aishell__terraform_destroy. Do not use `POST`/`PUT`/`DELETE` on aishell__openapi_request to create or destroy resources unless the user explicitly asks for the API route and understands the consequences: it skips the cost gate, never enters tfstate, and leaves no trace.\n- Before applying or destroying, name the resources involved and get the user's explicit agreement. Never run these silently.\n- A `.tf` file must never contain a plaintext `access_key`, `secret_key` or `security_token`. The scan runs before init and apply and refuses the run.\n- `cost.json` must exist and its `tf_hash` must match before apply. Editing a `.tf` file invalidates it; recompute the cost.\n- Other `POST`/`DELETE` calls (issuing a voucher, adjusting a quota \u2014 not resource lifecycle) do run, and return a warning. Pass that warning to the user.\n\n## Mainland region filing\n\nIn mainland regions (cn-north-1, cn-north-4, cn-east-3 and others), serving web traffic on ports 80/443 requires ICP filing. Traffic is blocked without it. If the user wants a web port, ask about their filing status first.\n\n## Typical requests\n\n- \"How many ECS instances do I have?\" \u2192 aishell__list_existing_resources with `service: \"ecs\"`\n- \"What did I spend this month?\" \u2192 aishell__openapi_request(\"GET\", <BSS bill API>)\n- \"How many vouchers do I have?\" \u2192 the `balance_summary` field of aishell__list_existing_resources\n- \"What arguments does this resource take?\" \u2192 aishell__provider_schema(deployment, \"huaweicloud_compute_instance\")\n- \"Tear this deployment down\" \u2192 aishell__terraform_destroy, after listing the resources for confirmation\n- \"The cloud changed, resync\" \u2192 aishell__terraform_refresh, then aishell__terraform_plan for the difference\n- \"What is deployed right now?\" \u2192 aishell__terraform_state\n- \"Bring this existing instance under management\" \u2192 write the resource block, then aishell__terraform_import\n\n## Product documentation\n\nFor what a Huawei Cloud product *is* \u2014 features, quotas, limits, charging models \u2014 read the index at https://support.huaweicloud.com/llms.txt. It lists every product's documentation entry point by category; read it to locate the product, then that product's own `llms.txt` for detail.\n\nDo not answer questions about a product's feature boundaries, quotas or charging rules from memory \u2014 they change between releases. For API contracts use aishell__apiexplorer; for what exists in the account use aishell__list_existing_resources; this index is for \"what is this product and what are its limits\".";
49
+ /**
50
+ * Register the workflow section.
51
+ *
52
+ * Deferred behind `ctx.inject` rather than declared in this plugin's own
53
+ * `inject`: the workflow is an enhancement, and a deployment without a system
54
+ * prompt should lose the guidance rather than fail to mount.
55
+ *
56
+ * @param ctx - host context.
57
+ */
58
+ export declare function registerDeployWorkflow(ctx: Context): void;
59
+ //# sourceMappingURL=prompt.d.ts.map
@@ -0,0 +1,108 @@
1
+ /**
2
+ * cost.json zod schema.
3
+ *
4
+ * Two charging shapes (§5.3):
5
+ * Shape A (包周期类): mode prepaid|on-demand, period/period_unit/auto_renew
6
+ * Shape B (带宽类): mode bandwidth|traffic, share_type/size
7
+ *
8
+ * cost.json uses lowercase/hyphen mode values (prepaid/on-demand); the
9
+ * provider uses camelCase (prePaid/postPaid). The translation mapping
10
+ * (§5.3) is documented in the design doc — server does NOT validate
11
+ * charging↔.tf consistency (HCL semantics, out of scope).
12
+ */
13
+ import { z } from "zod";
14
+ declare const chargingSchema: z.ZodObject<{
15
+ mode: z.ZodEnum<{
16
+ bandwidth: "bandwidth";
17
+ prepaid: "prepaid";
18
+ "on-demand": "on-demand";
19
+ traffic: "traffic";
20
+ }>;
21
+ period: z.ZodOptional<z.ZodNumber>;
22
+ period_unit: z.ZodOptional<z.ZodEnum<{
23
+ month: "month";
24
+ year: "year";
25
+ }>>;
26
+ auto_renew: z.ZodOptional<z.ZodBoolean>;
27
+ share_type: z.ZodOptional<z.ZodEnum<{
28
+ PER: "PER";
29
+ WHOLE: "WHOLE";
30
+ STANDARD: "STANDARD";
31
+ }>>;
32
+ size: z.ZodOptional<z.ZodNumber>;
33
+ }, z.core.$strip>;
34
+ declare const costItemSchema: z.ZodObject<{
35
+ resource: z.ZodString;
36
+ source: z.ZodEnum<{
37
+ reuse: "reuse";
38
+ new: "new";
39
+ }>;
40
+ existing_id: z.ZodOptional<z.ZodString>;
41
+ spec: z.ZodString;
42
+ charging: z.ZodObject<{
43
+ mode: z.ZodEnum<{
44
+ bandwidth: "bandwidth";
45
+ prepaid: "prepaid";
46
+ "on-demand": "on-demand";
47
+ traffic: "traffic";
48
+ }>;
49
+ period: z.ZodOptional<z.ZodNumber>;
50
+ period_unit: z.ZodOptional<z.ZodEnum<{
51
+ month: "month";
52
+ year: "year";
53
+ }>>;
54
+ auto_renew: z.ZodOptional<z.ZodBoolean>;
55
+ share_type: z.ZodOptional<z.ZodEnum<{
56
+ PER: "PER";
57
+ WHOLE: "WHOLE";
58
+ STANDARD: "STANDARD";
59
+ }>>;
60
+ size: z.ZodOptional<z.ZodNumber>;
61
+ }, z.core.$strip>;
62
+ monthly: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<null>]>;
63
+ }, z.core.$strip>;
64
+ export declare const CostSchema: z.ZodObject<{
65
+ $schema: z.ZodOptional<z.ZodString>;
66
+ currency: z.ZodEnum<{
67
+ CNY: "CNY";
68
+ USD: "USD";
69
+ }>;
70
+ items: z.ZodArray<z.ZodObject<{
71
+ resource: z.ZodString;
72
+ source: z.ZodEnum<{
73
+ reuse: "reuse";
74
+ new: "new";
75
+ }>;
76
+ existing_id: z.ZodOptional<z.ZodString>;
77
+ spec: z.ZodString;
78
+ charging: z.ZodObject<{
79
+ mode: z.ZodEnum<{
80
+ bandwidth: "bandwidth";
81
+ prepaid: "prepaid";
82
+ "on-demand": "on-demand";
83
+ traffic: "traffic";
84
+ }>;
85
+ period: z.ZodOptional<z.ZodNumber>;
86
+ period_unit: z.ZodOptional<z.ZodEnum<{
87
+ month: "month";
88
+ year: "year";
89
+ }>>;
90
+ auto_renew: z.ZodOptional<z.ZodBoolean>;
91
+ share_type: z.ZodOptional<z.ZodEnum<{
92
+ PER: "PER";
93
+ WHOLE: "WHOLE";
94
+ STANDARD: "STANDARD";
95
+ }>>;
96
+ size: z.ZodOptional<z.ZodNumber>;
97
+ }, z.core.$strip>;
98
+ monthly: z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<null>]>;
99
+ }, z.core.$strip>>;
100
+ total_monthly: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<null>]>>;
101
+ tf_hash: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<null>]>>;
102
+ estimated_at: z.ZodOptional<z.ZodString>;
103
+ }, z.core.$strip>;
104
+ export type Cost = z.infer<typeof CostSchema>;
105
+ export type CostItem = z.infer<typeof costItemSchema>;
106
+ export type Charging = z.infer<typeof chargingSchema>;
107
+ export {};
108
+ //# sourceMappingURL=cost.d.ts.map