@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.
- package/LICENSE +201 -0
- package/README.md +164 -2
- package/cordis.patch.yml +15 -0
- package/lib/data/permission-registry.json +1 -0
- package/lib/data/terraform-examples.zip +0 -0
- package/lib/index.js +4796 -0
- package/lib/types/auth-http.d.ts +44 -0
- package/lib/types/auth-obs-signer.d.ts +46 -0
- package/lib/types/auth-signer.d.ts +46 -0
- package/lib/types/bridge.d.ts +70 -0
- package/lib/types/credentials.d.ts +105 -0
- package/lib/types/data-paths.d.ts +70 -0
- package/lib/types/deployment-state.d.ts +69 -0
- package/lib/types/gates/cost_gate.d.ts +24 -0
- package/lib/types/gates/credential_gate.d.ts +21 -0
- package/lib/types/gates/mirror.d.ts +27 -0
- package/lib/types/gates/networking_gate.d.ts +9 -0
- package/lib/types/gates/terraform_env.d.ts +26 -0
- package/lib/types/index.d.ts +96 -0
- package/lib/types/permission/gate.d.ts +87 -0
- package/lib/types/permission/mode.d.ts +69 -0
- package/lib/types/permission/registry.d.ts +109 -0
- package/lib/types/permission-context.d.ts +84 -0
- package/lib/types/permission-route.d.ts +78 -0
- package/lib/types/permission.d.ts +37 -0
- package/lib/types/prompt.d.ts +59 -0
- package/lib/types/schemas/cost.d.ts +108 -0
- package/lib/types/schemas/networking.d.ts +115 -0
- package/lib/types/security-groups.d.ts +43 -0
- package/lib/types/tools/annotations.d.ts +94 -0
- package/lib/types/tools/balance_summary.d.ts +69 -0
- package/lib/types/tools/cost.d.ts +16 -0
- package/lib/types/tools/deployment.d.ts +14 -0
- package/lib/types/tools/errors.d.ts +40 -0
- package/lib/types/tools/examples.d.ts +4 -0
- package/lib/types/tools/existing_resources.d.ts +29 -0
- package/lib/types/tools/index.d.ts +32 -0
- package/lib/types/tools/networking.d.ts +13 -0
- package/lib/types/tools/openapi.d.ts +113 -0
- package/lib/types/tools/provider_schema.d.ts +19 -0
- package/lib/types/tools/terraform.d.ts +32 -0
- package/lib/types/types.d.ts +84 -0
- package/lib/types/utils/hash.d.ts +11 -0
- package/lib/types/utils/tar.d.ts +29 -0
- package/lib/types/version.d.ts +18 -0
- 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
|