@cerebriline/core 4.100.240

package/dist/extensions/tools/qa-credentials.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Credentials a QA run needs, kept out of the model's context.
+ *
+ * The request behind this (#46) is "let the agent log in so it can test what it
+ * just changed". The obvious implementations are both wrong, and it is worth
+ * naming them because they are what this exists instead of:
+ *
+ *   - **Ask for the credential in the conversation.** It is then in the
+ *     transcript, in whatever the provider logs, and in every request until
+ *     compaction drops it -- and the model forgets it long before that, so it
+ *     asks again.
+ *   - **Export it into the shell.** A terminal outlives the command that needed
+ *     the secret. Everything the model runs afterwards inherits it, including
+ *     the commands the model wrote itself, and any of them can print it.
+ *
+ * What this module does instead rests on three rules, none of which depend on
+ * what the project under test looks like:
+ *
+ *   1. The model is told the *names* and never the values.
+ *   2. A value reaches a command's environment only when that command asked for
+ *      it -- by naming it in the command text, or by listing it on the call.
+ *      Nothing else in the run carries it.
+ *   3. Every value is masked out of tool output before it becomes transcript.
+ *
+ * Rule 3 is the one that makes the rest safe in practice, because rules 1 and 2
+ * are about what we hand out and rule 3 is about what comes back. `echo
+ * $QA_PASSWORD`, a test runner that dumps its resolved config, a stack trace
+ * with a connection string in it -- all of them return through the same choke
+ * point, and all of them come back masked.
+ *
+ * The environment variable is the interface on purpose. It is the one thing a
+ * seeded-user script, a `curl` with a bearer token, a Playwright config and a
+ * `docker compose` file all agree on, so nothing here needs to know which of
+ * those the user has.
+ *
+ * **What this does not defend against**: a model that decides to exfiltrate. If
+ * it can put `$QA_PASSWORD` in a command it can put it in a request to a server
+ * it chose. That is inherent in giving a credential to a program at all, which
+ * is why the setting says test and sandbox credentials only. The guarantee here
+ * is against accident and drift -- the secret leaking into a transcript, a log,
+ * or an unrelated command -- not against intent.
+ */
+import type { StructuredCommandInput } from "./schemas";
+/** A named secret the user has made available to QA runs. */
+export interface QaCredential {
+    /** Environment variable name. What the model sees. */
+    name: string;
+    /** The secret itself. Never leaves this process except into a child's env. */
+    value: string;
+}
+/** A credential that was refused, and why, so a host can say so. */
+export interface RejectedQaCredential {
+    name: string;
+    reason: string;
+}
+export interface NormalizedQaCredentials {
+    credentials: QaCredential[];
+    rejected: RejectedQaCredential[];
+}
+/**
+ * Valid as an environment variable name across the shells we spawn.
+ *
+ * Deliberately narrower than POSIX allows: no leading digit, nothing outside
+ * word characters, and bounded, because a name is also what gets pattern-matched
+ * against command text and rendered into a tool description.
+ */
+export declare const QA_CREDENTIAL_NAME_PATTERN: RegExp;
+/**
+ * The shortest value that can be masked without shredding the output around it.
+ *
+ * A four-character secret appears inside ordinary words; redacting every
+ * occurrence would replace half a build log. Since a value that cannot be masked
+ * cannot be handled safely by rule 3, it is refused rather than accepted and
+ * quietly left unmasked -- the caller gets a reason it can show.
+ */
+export declare const QA_CREDENTIAL_MIN_VALUE_LENGTH = 8;
+/**
+ * Sort out what can be used from what the user typed.
+ *
+ * Everything refused comes back with a reason instead of being dropped: a
+ * credential that silently does not exist is indistinguishable, from the user's
+ * side, from a QA run that failed for some other reason.
+ */
+export declare function normalizeQaCredentials(credentials: readonly QaCredential[] | undefined): NormalizedQaCredentials;
+/** The part of a credential set the model is allowed to know. */
+export declare function qaCredentialNames(credentials: readonly QaCredential[]): string[];
+/** The text of a command, whichever shape `run_commands` delivered it in. */
+export declare function commandText(command: string | StructuredCommandInput): string;
+/**
+ * Which credentials a command asked for by writing them into itself.
+ *
+ * This exists so the common one-liner -- `curl -H "Authorization: Bearer
+ * $QA_API_KEY" ...` -- works without the model also having to declare what it
+ * just wrote. It is a convenience, not the whole gate: a command like `npx
+ * playwright test`, where the *framework* reads the environment and the command
+ * line mentions nothing, is the majority case and is covered by the explicit
+ * list instead.
+ */
+export declare function referencedCredentialNames(text: string, names: readonly string[]): string[];
+export interface CredentialEnvRequest {
+    /** The command about to run, if the caller has it. */
+    command?: string | StructuredCommandInput;
+    /** Names the call asked for explicitly. */
+    requested?: readonly string[];
+}
+/**
+ * The environment a single command gets: nothing unless it asked.
+ *
+ * Returns an empty object rather than the whole set when nothing matched, which
+ * is what keeps `ls`, `git status` and every other incidental command in a run
+ * from carrying secrets they have no use for.
+ */
+export declare function resolveCredentialEnv(credentials: readonly QaCredential[], request: CredentialEnvRequest): Record<string, string>;
+/**
+ * Replace every configured value wherever it appears in text.
+ *
+ * Longest first, so a value that contains another value masks as itself rather
+ * than being chewed into pieces by the shorter one.
+ *
+ * The replacement names the credential on purpose: `[redacted: QA_PASSWORD]`
+ * tells the model that the thing it is looking for was there and was withheld,
+ * which is actionable. A blank, or nothing at all, reads as a bug in the tool
+ * and gets retried.
+ */
+export declare function createSecretRedactor(credentials: readonly QaCredential[]): (text: string) => string;
+/**
+ * What the model is told, appended to the `run_commands` description.
+ *
+ * In the tool description rather than the system prompt because that is where a
+ * model looks when it is deciding how to call the tool, and because the names
+ * are only meaningful next to the parameter that uses them.
+ */
+export declare function describeQaCredentials(names: readonly string[]): string;

package/dist/extensions/tools/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { CoreAgentMode } from "../../types/config";
+export interface ToolCatalogEntry {
+    id: string;
+    description: string;
+    defaultEnabled: boolean;
+    headlessToolNames: string[];
+    unavailableClientTypes?: readonly ToolClientType[];
+}
+export type ToolClientType = "cli" | "vscode";
+export declare function resolveToolClientType(source?: string): ToolClientType | undefined;
+export interface BuiltinToolAvailabilityContext {
+    mode?: CoreAgentMode;
+    clientType?: ToolClientType;
+    providerId?: string;
+    modelId?: string;
+    enableSpawnAgent?: boolean;
+    enableAgentTeams?: boolean;
+    disabledToolIds?: ReadonlySet<string>;
+    enabledModelToolIds?: ReadonlySet<string>;
+}
+export declare function isCoreBuiltinToolAvailable(toolName: string, clientType?: ToolClientType): boolean;
+export declare function getCoreBuiltinToolCatalog(context?: BuiltinToolAvailabilityContext): ToolCatalogEntry[];
+/**
+ * Whether the `skills` tool is part of a session's default toolset for this
+ * availability context. Hosts consult this before dispatching a typed
+ * `/skill` command: when the tool is available the command passes through as
+ * typed and the model loads the instructions via the tool; when it is not
+ * (e.g. the yolo preset or a user toggle disables it), textual expansion is
+ * the only delivery path left.
+ */
+export declare function isSkillsToolAvailable(context?: BuiltinToolAvailabilityContext): boolean;
+export declare function getCoreDefaultEnabledToolIds(context?: BuiltinToolAvailabilityContext): string[];
+export declare function resolveCoreSelectedToolIds(input: {
+    enabled: boolean;
+    allowlist?: string[];
+    availabilityContext?: BuiltinToolAvailabilityContext;
+}): Set<string>;
+export declare function getCoreHeadlessToolNames(selectedToolIds: ReadonlySet<string>, context?: BuiltinToolAvailabilityContext): string[];
+export declare function getCoreAcpToolNames(selectedToolIds: ReadonlySet<string>, context?: BuiltinToolAvailabilityContext): string[];