@alauda/doom 2.5.4 → 2.6.1
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/lib/cli/api.d.ts +2 -0
- package/lib/cli/api.js +147 -0
- package/lib/cli/helpers.d.ts +1 -7
- package/lib/cli/helpers.js +4 -41
- package/lib/cli/index.js +2 -0
- package/lib/cli/translate-agent.d.ts +81 -0
- package/lib/cli/translate-agent.js +450 -0
- package/lib/cli/translate-check.d.ts +17 -0
- package/lib/cli/translate-check.js +67 -0
- package/lib/cli/translate-checker.d.ts +58 -0
- package/lib/cli/translate-checker.js +112 -0
- package/lib/cli/translate-judge.d.ts +119 -0
- package/lib/cli/translate-judge.js +224 -0
- package/lib/cli/translate-limits.d.ts +43 -0
- package/lib/cli/translate-limits.js +55 -0
- package/lib/cli/translate-mask.d.ts +144 -0
- package/lib/cli/translate-mask.js +617 -0
- package/lib/cli/translate-models.d.ts +127 -0
- package/lib/cli/translate-models.js +189 -0
- package/lib/cli/translate-scratch.d.ts +142 -0
- package/lib/cli/translate-scratch.js +187 -0
- package/lib/cli/translate-terms.d.ts +22 -0
- package/lib/cli/translate-terms.js +33 -0
- package/lib/cli/translate.d.ts +15 -10
- package/lib/cli/translate.js +228 -185
- package/lib/eslint.js +22 -3
- package/lib/plugins/api/index.js +1 -1
- package/lib/plugins/api/types.d.ts +36 -1
- package/lib/plugins/global/components.d.ts +16 -0
- package/lib/plugins/global/components.js +16 -1
- package/lib/remark-lint/index.d.ts +20 -0
- package/lib/remark-lint/index.js +40 -0
- package/lib/remark-lint/no-unmatched-anchor.d.ts +10 -0
- package/lib/remark-lint/no-unmatched-anchor.js +19 -2
- package/lib/remark-lint/no-unopened-frontmatter.d.ts +2 -0
- package/lib/remark-lint/no-unopened-frontmatter.js +70 -0
- package/lib/remark-lint/no-unparsed-emphasis.d.ts +2 -0
- package/lib/remark-lint/no-unparsed-emphasis.js +53 -0
- package/lib/remark-lint/no-unresolved-api-ref.d.ts +40 -0
- package/lib/remark-lint/no-unresolved-api-ref.js +194 -0
- package/lib/remark-lint/rule-sets.d.ts +73 -0
- package/lib/remark-lint/rule-sets.js +114 -0
- package/lib/remark-lint/syntax-plugins.d.ts +32 -0
- package/lib/remark-lint/syntax-plugins.js +46 -0
- package/lib/remark-lint/translation-parity/component-multiset.d.ts +17 -0
- package/lib/remark-lint/translation-parity/component-multiset.js +35 -0
- package/lib/remark-lint/translation-parity/echoed-source.d.ts +2 -0
- package/lib/remark-lint/translation-parity/echoed-source.js +37 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.d.ts +2 -0
- package/lib/remark-lint/translation-parity/frontmatter-preservation.js +36 -0
- package/lib/remark-lint/translation-parity/heading-sequence.d.ts +12 -0
- package/lib/remark-lint/translation-parity/heading-sequence.js +25 -0
- package/lib/remark-lint/translation-parity/index.d.ts +24 -0
- package/lib/remark-lint/translation-parity/index.js +24 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.d.ts +14 -0
- package/lib/remark-lint/translation-parity/jsx-attribute-parity.js +47 -0
- package/lib/remark-lint/translation-parity/length-ratio.d.ts +2 -0
- package/lib/remark-lint/translation-parity/length-ratio.js +49 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.d.ts +34 -0
- package/lib/remark-lint/translation-parity/link-isomorphism.js +81 -0
- package/lib/remark-lint/translation-parity/shared.d.ts +110 -0
- package/lib/remark-lint/translation-parity/shared.js +286 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.d.ts +2 -0
- package/lib/remark-lint/translation-parity/terminology-adherence.js +67 -0
- package/lib/remark-lint/translation-parity/up-to-date.d.ts +11 -0
- package/lib/remark-lint/translation-parity/up-to-date.js +21 -0
- package/lib/remark-lint/translation-parity/url-residue.d.ts +3 -0
- package/lib/remark-lint/translation-parity/url-residue.js +67 -0
- package/lib/remarkrc.d.ts +1 -1
- package/lib/remarkrc.js +7 -34
- package/lib/runtime/api-paths.d.ts +20 -0
- package/lib/runtime/api-paths.js +29 -0
- package/lib/runtime/components/K8sAPI.d.ts +14 -1
- package/lib/runtime/components/K8sAPI.js +49 -10
- package/lib/runtime/components/K8sCrd.d.ts +1 -1
- package/lib/runtime/components/K8sPermissionTable.js +10 -5
- package/lib/runtime/components/OpenAPIPath.js +19 -2
- package/lib/runtime/components/_HeadingTitle.js +24 -6
- package/lib/runtime/components/_K8sAPIEndpoints.d.ts +8 -1
- package/lib/runtime/components/_K8sAPIEndpoints.js +27 -9
- package/lib/runtime/components/_K8sAPISchema.d.ts +9 -1
- package/lib/runtime/components/_K8sAPISchema.js +24 -6
- package/lib/runtime/components/_translation-policy.d.ts +23 -0
- package/lib/runtime/components/_translation-policy.js +32 -0
- package/lib/runtime/hooks/useTranslation.d.ts +1 -1
- package/lib/runtime/translation.d.ts +68 -0
- package/lib/runtime/translation.js +51 -0
- package/lib/runtime/utils.d.ts +24 -2
- package/lib/runtime/utils.js +87 -5
- package/lib/shared/constants.d.ts +9 -0
- package/lib/shared/constants.js +14 -0
- package/lib/types.d.ts +70 -0
- package/lib/utils/helpers.js +8 -2
- package/package.json +3 -1
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
import type { Model, Models, ThinkingLevel } from '@earendil-works/pi-ai';
|
|
2
|
+
/**
|
|
3
|
+
* The translation gateway, described to pi.
|
|
4
|
+
*
|
|
5
|
+
* The gateway is an OpenAI-compatible endpoint reached through
|
|
6
|
+
* `ALAUDA_OPENAI_BASE_URL` / `ALAUDA_OPENAI_API_KEY`, which is how
|
|
7
|
+
* `doom translate` has always reached it. pi wants a provider and a model
|
|
8
|
+
* object rather than a base url and a model name, so this builds them.
|
|
9
|
+
*/
|
|
10
|
+
export declare const GATEWAY_PROVIDER_ID = "alauda";
|
|
11
|
+
/** The default translator model. Measured against this gateway; see the proposal's §5.4. */
|
|
12
|
+
export declare const DEFAULT_TRANSLATE_MODEL = "gpt-5.6";
|
|
13
|
+
/**
|
|
14
|
+
* The default reviewer, and deliberately not the translator.
|
|
15
|
+
*
|
|
16
|
+
* Two readings by one model share that model's blind spots, and a model asked
|
|
17
|
+
* to review what it just wrote prefers it. Neither is fixed by taking more
|
|
18
|
+
* draws — only by asking something else.
|
|
19
|
+
*
|
|
20
|
+
* Measured on 40 held-out pairs against the translator reviewing itself: the
|
|
21
|
+
* same 18/20 injection recall, and no worse a false-positive rate. The reason
|
|
22
|
+
* to prefer it is the failures it does not share, not a better score.
|
|
23
|
+
*/
|
|
24
|
+
export declare const DEFAULT_JUDGE_MODEL = "grok-4.6";
|
|
25
|
+
export declare const DEFAULT_REASONING_EFFORT: ThinkingLevel;
|
|
26
|
+
/**
|
|
27
|
+
* The judge reads rather than writes, and reading two documents against each
|
|
28
|
+
* other is the harder job — so it gets a step more reasoning than the
|
|
29
|
+
* translator. Both families this gateway serves accept this level; they
|
|
30
|
+
* disagree only at the ends of the scale.
|
|
31
|
+
*/
|
|
32
|
+
export declare const DEFAULT_JUDGE_REASONING_EFFORT: ThinkingLevel;
|
|
33
|
+
/**
|
|
34
|
+
* How much of the model's context we plan for.
|
|
35
|
+
*
|
|
36
|
+
* Deliberately conservative, and deliberately not the number the gateway
|
|
37
|
+
* reports. A context window is a property of one model on one gateway on one
|
|
38
|
+
* day: reading it once and building on it is how the previous design talked
|
|
39
|
+
* itself out of segmenting documents at all. Planning for less than we have
|
|
40
|
+
* costs a few extra reads; planning for more than we have loses content.
|
|
41
|
+
*/
|
|
42
|
+
export declare const DEFAULT_CONTEXT_WINDOW = 128000;
|
|
43
|
+
/**
|
|
44
|
+
* The cap pi puts on a single response.
|
|
45
|
+
*
|
|
46
|
+
* pi always sends one (`options.maxTokens ?? model.maxTokens`), where the old
|
|
47
|
+
* single-shot translator sent none. That is a real difference in behaviour, so
|
|
48
|
+
* it is a named number rather than an incidental one — and it is not the thing
|
|
49
|
+
* keeping long documents intact. The agent writes a long translation in
|
|
50
|
+
* segments, and a response cut short leaves placeholders unaccounted for,
|
|
51
|
+
* which the mask assertions report.
|
|
52
|
+
*/
|
|
53
|
+
export declare const DEFAULT_MAX_OUTPUT_TOKENS = 32000;
|
|
54
|
+
/**
|
|
55
|
+
* Which vocabulary a model id speaks.
|
|
56
|
+
*
|
|
57
|
+
* The gateway exposes the same model under several ids — `grok-4.6`,
|
|
58
|
+
* `grok/grok-4.6`, `x-ai/grok-4.6`, `xai/grok-4.6` — so this matches the family
|
|
59
|
+
* anywhere in the id rather than anchoring at the start.
|
|
60
|
+
*
|
|
61
|
+
* An unknown model gets the `gpt-*` vocabulary, because that is the family this
|
|
62
|
+
* gateway has always served and the one every default here names. That is a
|
|
63
|
+
* guess, and a wrong guess shows up as a 400 naming the level — loudly, on the
|
|
64
|
+
* first call, not as a silently degraded translation.
|
|
65
|
+
*/
|
|
66
|
+
export declare const thinkingLevelsFor: (modelId: string) => {
|
|
67
|
+
readonly off: "none";
|
|
68
|
+
readonly minimal: null;
|
|
69
|
+
readonly low: "low";
|
|
70
|
+
readonly medium: "medium";
|
|
71
|
+
readonly high: "high";
|
|
72
|
+
readonly xhigh: "xhigh";
|
|
73
|
+
readonly max: "max";
|
|
74
|
+
} | {
|
|
75
|
+
readonly off: null;
|
|
76
|
+
readonly minimal: "minimal";
|
|
77
|
+
readonly low: "low";
|
|
78
|
+
readonly medium: "medium";
|
|
79
|
+
readonly high: "high";
|
|
80
|
+
readonly xhigh: "xhigh";
|
|
81
|
+
readonly max: "max";
|
|
82
|
+
};
|
|
83
|
+
export interface GatewayModelOptions {
|
|
84
|
+
id: string;
|
|
85
|
+
baseUrl: string;
|
|
86
|
+
contextWindow?: number;
|
|
87
|
+
maxOutputTokens?: number;
|
|
88
|
+
}
|
|
89
|
+
export declare const gatewayModel: ({ id, baseUrl, contextWindow, maxOutputTokens, }: GatewayModelOptions) => Model<"openai-completions">;
|
|
90
|
+
export declare class MissingGatewayCredentialsError extends Error {
|
|
91
|
+
constructor(missing: readonly string[]);
|
|
92
|
+
}
|
|
93
|
+
export declare const API_KEY_ENV = "ALAUDA_OPENAI_API_KEY";
|
|
94
|
+
export declare const BASE_URL_ENV = "ALAUDA_OPENAI_BASE_URL";
|
|
95
|
+
/**
|
|
96
|
+
* Which model reviews the translations, when it should not be the one that
|
|
97
|
+
* wrote them.
|
|
98
|
+
*
|
|
99
|
+
* An environment variable rather than only `translate.judge.model` because the
|
|
100
|
+
* judge is a property of the *gateway* the build talks to, not of the site
|
|
101
|
+
* being built: switching it in config means editing every documentation
|
|
102
|
+
* repository, and leaves them free to drift apart. The per-site option still
|
|
103
|
+
* wins, for a repository that has a reason to differ.
|
|
104
|
+
*/
|
|
105
|
+
export declare const JUDGE_MODEL_ENV = "ALAUDA_OPENAI_JUDGE_MODEL";
|
|
106
|
+
export interface Gateway {
|
|
107
|
+
models: Models;
|
|
108
|
+
/** The model that writes translations. */
|
|
109
|
+
model: Model<'openai-completions'>;
|
|
110
|
+
/** The model that reviews them — `DEFAULT_JUDGE_MODEL` unless configured otherwise. */
|
|
111
|
+
judgeModel: Model<'openai-completions'>;
|
|
112
|
+
baseUrl: string;
|
|
113
|
+
}
|
|
114
|
+
export interface CreateGatewayOptions {
|
|
115
|
+
modelId?: string;
|
|
116
|
+
judgeModelId?: string;
|
|
117
|
+
contextWindow?: number;
|
|
118
|
+
maxOutputTokens?: number;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Wires the gateway up as a pi provider.
|
|
122
|
+
*
|
|
123
|
+
* Fails immediately and by name when a credential is missing. The alternative
|
|
124
|
+
* — discovering it one stream error at a time, once per file — is how a
|
|
125
|
+
* misconfigured run turns into a wall of unrelated failures.
|
|
126
|
+
*/
|
|
127
|
+
export declare const createGateway: ({ modelId, judgeModelId, contextWindow, maxOutputTokens, }?: CreateGatewayOptions) => Promise<Gateway>;
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The translation gateway, described to pi.
|
|
3
|
+
*
|
|
4
|
+
* The gateway is an OpenAI-compatible endpoint reached through
|
|
5
|
+
* `ALAUDA_OPENAI_BASE_URL` / `ALAUDA_OPENAI_API_KEY`, which is how
|
|
6
|
+
* `doom translate` has always reached it. pi wants a provider and a model
|
|
7
|
+
* object rather than a base url and a model name, so this builds them.
|
|
8
|
+
*/
|
|
9
|
+
export const GATEWAY_PROVIDER_ID = 'alauda';
|
|
10
|
+
/** The default translator model. Measured against this gateway; see the proposal's §5.4. */
|
|
11
|
+
export const DEFAULT_TRANSLATE_MODEL = 'gpt-5.6';
|
|
12
|
+
/**
|
|
13
|
+
* The default reviewer, and deliberately not the translator.
|
|
14
|
+
*
|
|
15
|
+
* Two readings by one model share that model's blind spots, and a model asked
|
|
16
|
+
* to review what it just wrote prefers it. Neither is fixed by taking more
|
|
17
|
+
* draws — only by asking something else.
|
|
18
|
+
*
|
|
19
|
+
* Measured on 40 held-out pairs against the translator reviewing itself: the
|
|
20
|
+
* same 18/20 injection recall, and no worse a false-positive rate. The reason
|
|
21
|
+
* to prefer it is the failures it does not share, not a better score.
|
|
22
|
+
*/
|
|
23
|
+
export const DEFAULT_JUDGE_MODEL = 'grok-4.6';
|
|
24
|
+
export const DEFAULT_REASONING_EFFORT = 'low';
|
|
25
|
+
/**
|
|
26
|
+
* The judge reads rather than writes, and reading two documents against each
|
|
27
|
+
* other is the harder job — so it gets a step more reasoning than the
|
|
28
|
+
* translator. Both families this gateway serves accept this level; they
|
|
29
|
+
* disagree only at the ends of the scale.
|
|
30
|
+
*/
|
|
31
|
+
export const DEFAULT_JUDGE_REASONING_EFFORT = 'medium';
|
|
32
|
+
/**
|
|
33
|
+
* How much of the model's context we plan for.
|
|
34
|
+
*
|
|
35
|
+
* Deliberately conservative, and deliberately not the number the gateway
|
|
36
|
+
* reports. A context window is a property of one model on one gateway on one
|
|
37
|
+
* day: reading it once and building on it is how the previous design talked
|
|
38
|
+
* itself out of segmenting documents at all. Planning for less than we have
|
|
39
|
+
* costs a few extra reads; planning for more than we have loses content.
|
|
40
|
+
*/
|
|
41
|
+
export const DEFAULT_CONTEXT_WINDOW = 128_000;
|
|
42
|
+
/**
|
|
43
|
+
* The cap pi puts on a single response.
|
|
44
|
+
*
|
|
45
|
+
* pi always sends one (`options.maxTokens ?? model.maxTokens`), where the old
|
|
46
|
+
* single-shot translator sent none. That is a real difference in behaviour, so
|
|
47
|
+
* it is a named number rather than an incidental one — and it is not the thing
|
|
48
|
+
* keeping long documents intact. The agent writes a long translation in
|
|
49
|
+
* segments, and a response cut short leaves placeholders unaccounted for,
|
|
50
|
+
* which the mask assertions report.
|
|
51
|
+
*/
|
|
52
|
+
export const DEFAULT_MAX_OUTPUT_TOKENS = 32_000;
|
|
53
|
+
/**
|
|
54
|
+
* What the gateway calls each reasoning level.
|
|
55
|
+
*
|
|
56
|
+
* This is a property of the *model*, not of the gateway. It reads like a
|
|
57
|
+
* gateway constant — one endpoint, one vocabulary — and that was true while the
|
|
58
|
+
* gateway served one model family. It is not true now, and the two families
|
|
59
|
+
* disagree on exactly the two ends of the scale:
|
|
60
|
+
*
|
|
61
|
+
* | level | `gpt-*` | `grok-*` |
|
|
62
|
+
* | --------- | ------- | -------- |
|
|
63
|
+
* | `none` | ok | **400** |
|
|
64
|
+
* | `minimal` | **400** | ok |
|
|
65
|
+
*
|
|
66
|
+
* So a single map cannot describe both: whichever one it is written for, it
|
|
67
|
+
* makes the other 400 at the edges. An unsupported level is `null`, which pi
|
|
68
|
+
* clamps to the nearest one the model does have.
|
|
69
|
+
*
|
|
70
|
+
* Re-measure by POSTing `/chat/completions` with each `reasoning_effort` value
|
|
71
|
+
* and reading the status — the levels are not discoverable from `/models`.
|
|
72
|
+
*/
|
|
73
|
+
const GPT_THINKING_LEVELS = {
|
|
74
|
+
off: 'none',
|
|
75
|
+
minimal: null,
|
|
76
|
+
low: 'low',
|
|
77
|
+
medium: 'medium',
|
|
78
|
+
high: 'high',
|
|
79
|
+
xhigh: 'xhigh',
|
|
80
|
+
max: 'max',
|
|
81
|
+
};
|
|
82
|
+
const GROK_THINKING_LEVELS = {
|
|
83
|
+
...GPT_THINKING_LEVELS,
|
|
84
|
+
off: null,
|
|
85
|
+
minimal: 'minimal',
|
|
86
|
+
};
|
|
87
|
+
/**
|
|
88
|
+
* Which vocabulary a model id speaks.
|
|
89
|
+
*
|
|
90
|
+
* The gateway exposes the same model under several ids — `grok-4.6`,
|
|
91
|
+
* `grok/grok-4.6`, `x-ai/grok-4.6`, `xai/grok-4.6` — so this matches the family
|
|
92
|
+
* anywhere in the id rather than anchoring at the start.
|
|
93
|
+
*
|
|
94
|
+
* An unknown model gets the `gpt-*` vocabulary, because that is the family this
|
|
95
|
+
* gateway has always served and the one every default here names. That is a
|
|
96
|
+
* guess, and a wrong guess shows up as a 400 naming the level — loudly, on the
|
|
97
|
+
* first call, not as a silently degraded translation.
|
|
98
|
+
*/
|
|
99
|
+
export const thinkingLevelsFor = (modelId) => /grok/i.test(modelId) ? GROK_THINKING_LEVELS : GPT_THINKING_LEVELS;
|
|
100
|
+
export const gatewayModel = ({ id, baseUrl, contextWindow = DEFAULT_CONTEXT_WINDOW, maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS, }) => ({
|
|
101
|
+
id,
|
|
102
|
+
name: id,
|
|
103
|
+
api: 'openai-completions',
|
|
104
|
+
provider: GATEWAY_PROVIDER_ID,
|
|
105
|
+
baseUrl,
|
|
106
|
+
reasoning: true,
|
|
107
|
+
thinkingLevelMap: { ...thinkingLevelsFor(id) },
|
|
108
|
+
input: ['text'],
|
|
109
|
+
// Billing for this gateway is not per-request, and nothing here reads cost.
|
|
110
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
111
|
+
contextWindow,
|
|
112
|
+
maxTokens: maxOutputTokens,
|
|
113
|
+
compat: {
|
|
114
|
+
// Stated rather than detected: detection keys off the base url, and this
|
|
115
|
+
// one is an internal host pi has never seen. All four were checked against
|
|
116
|
+
// the real gateway.
|
|
117
|
+
supportsStore: false,
|
|
118
|
+
supportsDeveloperRole: false,
|
|
119
|
+
supportsReasoningEffort: true,
|
|
120
|
+
maxTokensField: 'max_completion_tokens',
|
|
121
|
+
},
|
|
122
|
+
});
|
|
123
|
+
export class MissingGatewayCredentialsError extends Error {
|
|
124
|
+
constructor(missing) {
|
|
125
|
+
super(`Cannot translate: ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not set. ` +
|
|
126
|
+
'They point `doom translate` at the translation gateway.');
|
|
127
|
+
this.name = 'MissingGatewayCredentialsError';
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
export const API_KEY_ENV = 'ALAUDA_OPENAI_API_KEY';
|
|
131
|
+
export const BASE_URL_ENV = 'ALAUDA_OPENAI_BASE_URL';
|
|
132
|
+
/**
|
|
133
|
+
* Which model reviews the translations, when it should not be the one that
|
|
134
|
+
* wrote them.
|
|
135
|
+
*
|
|
136
|
+
* An environment variable rather than only `translate.judge.model` because the
|
|
137
|
+
* judge is a property of the *gateway* the build talks to, not of the site
|
|
138
|
+
* being built: switching it in config means editing every documentation
|
|
139
|
+
* repository, and leaves them free to drift apart. The per-site option still
|
|
140
|
+
* wins, for a repository that has a reason to differ.
|
|
141
|
+
*/
|
|
142
|
+
export const JUDGE_MODEL_ENV = 'ALAUDA_OPENAI_JUDGE_MODEL';
|
|
143
|
+
/**
|
|
144
|
+
* Wires the gateway up as a pi provider.
|
|
145
|
+
*
|
|
146
|
+
* Fails immediately and by name when a credential is missing. The alternative
|
|
147
|
+
* — discovering it one stream error at a time, once per file — is how a
|
|
148
|
+
* misconfigured run turns into a wall of unrelated failures.
|
|
149
|
+
*/
|
|
150
|
+
export const createGateway = async ({ modelId = process.env.ALAUDA_OPENAI_MODEL || DEFAULT_TRANSLATE_MODEL, judgeModelId = process.env[JUDGE_MODEL_ENV] || DEFAULT_JUDGE_MODEL, contextWindow, maxOutputTokens, } = {}) => {
|
|
151
|
+
const baseUrl = process.env[BASE_URL_ENV];
|
|
152
|
+
const missing = [
|
|
153
|
+
process.env[API_KEY_ENV] ? undefined : API_KEY_ENV,
|
|
154
|
+
baseUrl ? undefined : BASE_URL_ENV,
|
|
155
|
+
].filter((name) => !!name);
|
|
156
|
+
if (missing.length > 0 || !baseUrl) {
|
|
157
|
+
throw new MissingGatewayCredentialsError(missing);
|
|
158
|
+
}
|
|
159
|
+
const [{ createModels, createProvider, envApiKeyAuth }, { openAICompletionsApi },] = await Promise.all([
|
|
160
|
+
import('@earendil-works/pi-ai'),
|
|
161
|
+
import('@earendil-works/pi-ai/api/openai-completions.lazy'),
|
|
162
|
+
]);
|
|
163
|
+
const model = gatewayModel({
|
|
164
|
+
id: modelId,
|
|
165
|
+
baseUrl,
|
|
166
|
+
contextWindow,
|
|
167
|
+
maxOutputTokens,
|
|
168
|
+
});
|
|
169
|
+
const judgeModel = judgeModelId && judgeModelId !== modelId
|
|
170
|
+
? gatewayModel({
|
|
171
|
+
id: judgeModelId,
|
|
172
|
+
baseUrl,
|
|
173
|
+
contextWindow,
|
|
174
|
+
maxOutputTokens,
|
|
175
|
+
})
|
|
176
|
+
: model;
|
|
177
|
+
const models = createModels();
|
|
178
|
+
models.setProvider(createProvider({
|
|
179
|
+
id: GATEWAY_PROVIDER_ID,
|
|
180
|
+
name: 'Alauda translation gateway',
|
|
181
|
+
baseUrl,
|
|
182
|
+
auth: {
|
|
183
|
+
apiKey: envApiKeyAuth('Alauda translation gateway', [API_KEY_ENV]),
|
|
184
|
+
},
|
|
185
|
+
models: judgeModel === model ? [model] : [model, judgeModel],
|
|
186
|
+
api: openAICompletionsApi(),
|
|
187
|
+
}));
|
|
188
|
+
return { models, model, judgeModel, baseUrl };
|
|
189
|
+
};
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import type { ExecutionEnv, ExecutionError as ExecutionErrorType, FileError as FileErrorType, FileInfo, Result, ShellExecOptions } from '@earendil-works/pi-agent-core';
|
|
2
|
+
/**
|
|
3
|
+
* The namespace a translating agent lives in.
|
|
4
|
+
*
|
|
5
|
+
* Masking is what keeps a model from rewriting a link, an identifier or a code
|
|
6
|
+
* block: those values are replaced by opaque placeholders before the document
|
|
7
|
+
* is sent, so there is nothing in the model's context to rewrite. That
|
|
8
|
+
* guarantee is a property of the *namespace*, not of any individual tool — the
|
|
9
|
+
* unmasked bytes are never written into the scratch directory at all, so no
|
|
10
|
+
* tool can return them and no tool has to remember not to.
|
|
11
|
+
*
|
|
12
|
+
* Which is exactly why the filesystem the tools run against has to be confined.
|
|
13
|
+
* `NodeExecutionEnv` takes a `cwd`, but `cwd` only resolves *relative* paths:
|
|
14
|
+
* an absolute path goes wherever it says. Without this wrapper an agent that
|
|
15
|
+
* reads `/…/docs/en/install/installing.mdx` gets the real, unmasked source —
|
|
16
|
+
* and everything downstream stays green, because nothing about the run looks
|
|
17
|
+
* unusual. A protection that fails silently is the failure mode this whole
|
|
18
|
+
* proposal exists to remove, so it gets a wrapper and a test that proves the
|
|
19
|
+
* wrapper is load-bearing.
|
|
20
|
+
*/
|
|
21
|
+
/** Loaded lazily: pulling in pi costs ~450ms, and most doom commands never translate. */
|
|
22
|
+
export type PiNode = typeof import('@earendil-works/pi-agent-core/node');
|
|
23
|
+
export type PiCore = typeof import('@earendil-works/pi-agent-core');
|
|
24
|
+
export interface Pi {
|
|
25
|
+
core: PiCore;
|
|
26
|
+
NodeExecutionEnv: PiNode['NodeExecutionEnv'];
|
|
27
|
+
}
|
|
28
|
+
export declare const loadPi: () => Promise<Pi>;
|
|
29
|
+
export interface JailedExecutionEnvOptions {
|
|
30
|
+
/** Absolute path every operation is confined to. */
|
|
31
|
+
root: string;
|
|
32
|
+
/** The environment being wrapped. */
|
|
33
|
+
inner: ExecutionEnv;
|
|
34
|
+
/** `err`/`ok` and `FileError`/`ExecutionError` from pi, passed in to keep this module free of a static import. */
|
|
35
|
+
pi: Pick<PiCore, 'err' | 'ok' | 'FileError' | 'ExecutionError'>;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Confines an {@link ExecutionEnv} to one directory.
|
|
39
|
+
*
|
|
40
|
+
* Anything addressed outside it comes back `not_found` — the same answer as a
|
|
41
|
+
* path that does not exist, so the boundary does not double as an oracle for
|
|
42
|
+
* what lives beyond it.
|
|
43
|
+
*/
|
|
44
|
+
export declare class JailedExecutionEnv implements ExecutionEnv {
|
|
45
|
+
readonly cwd: string;
|
|
46
|
+
private readonly root;
|
|
47
|
+
private readonly inner;
|
|
48
|
+
private readonly pi;
|
|
49
|
+
constructor({ root, inner, pi }: JailedExecutionEnvOptions);
|
|
50
|
+
/** `not_found` for everything outside, so the jail reveals nothing about what is out there. */
|
|
51
|
+
private outside;
|
|
52
|
+
/**
|
|
53
|
+
* The addressed path, or `undefined` when it leaves the jail.
|
|
54
|
+
*
|
|
55
|
+
* Two checks, because either alone has a hole: the lexical one rejects
|
|
56
|
+
* `../../etc/passwd` without touching the disk, and the symlink one rejects a
|
|
57
|
+
* path that stays inside lexically but resolves outside.
|
|
58
|
+
*/
|
|
59
|
+
private confine;
|
|
60
|
+
private withPath;
|
|
61
|
+
absolutePath(target: string): Promise<Result<string, FileErrorType>>;
|
|
62
|
+
joinPath(parts: string[]): Promise<Result<string, FileErrorType>>;
|
|
63
|
+
/**
|
|
64
|
+
* Refused outright.
|
|
65
|
+
*
|
|
66
|
+
* The agent is given no shell tool, so nothing should reach this. It refuses
|
|
67
|
+
* anyway: the reason there is no shell is that a shell reads any file and runs
|
|
68
|
+
* any command in the build container, and that reason does not stop being true
|
|
69
|
+
* if someone later adds a tool that uses `exec`.
|
|
70
|
+
*/
|
|
71
|
+
exec(command: string, options?: ShellExecOptions): Promise<Result<{
|
|
72
|
+
stdout: string;
|
|
73
|
+
stderr: string;
|
|
74
|
+
exitCode: number;
|
|
75
|
+
}, ExecutionErrorType>>;
|
|
76
|
+
readTextFile(target: string, abortSignal?: AbortSignal): Promise<Result<string, FileErrorType>>;
|
|
77
|
+
readTextLines(target: string, options?: {
|
|
78
|
+
maxLines?: number;
|
|
79
|
+
abortSignal?: AbortSignal;
|
|
80
|
+
}): Promise<Result<string[], FileErrorType>>;
|
|
81
|
+
readBinaryFile(target: string, abortSignal?: AbortSignal): Promise<Result<Uint8Array<ArrayBufferLike>, FileErrorType>>;
|
|
82
|
+
writeFile(target: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileErrorType>>;
|
|
83
|
+
appendFile(target: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileErrorType>>;
|
|
84
|
+
renameFile(sourcePath: string, destinationPath: string, abortSignal?: AbortSignal): Promise<{
|
|
85
|
+
ok: false;
|
|
86
|
+
error: FileErrorType;
|
|
87
|
+
} | {
|
|
88
|
+
ok: true;
|
|
89
|
+
value: void;
|
|
90
|
+
}>;
|
|
91
|
+
fileInfo(target: string, abortSignal?: AbortSignal): Promise<Result<FileInfo, FileErrorType>>;
|
|
92
|
+
listDir(target: string, abortSignal?: AbortSignal): Promise<Result<FileInfo[], FileErrorType>>;
|
|
93
|
+
canonicalPath(target: string, abortSignal?: AbortSignal): Promise<Result<string, FileErrorType>>;
|
|
94
|
+
exists(target: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileErrorType>>;
|
|
95
|
+
createDir(target: string, options?: {
|
|
96
|
+
recursive?: boolean;
|
|
97
|
+
abortSignal?: AbortSignal;
|
|
98
|
+
}): Promise<Result<void, FileErrorType>>;
|
|
99
|
+
remove(target: string, options?: {
|
|
100
|
+
recursive?: boolean;
|
|
101
|
+
force?: boolean;
|
|
102
|
+
abortSignal?: AbortSignal;
|
|
103
|
+
}): Promise<Result<void, FileErrorType>>;
|
|
104
|
+
/** Redirected inside the jail: the wrapped environment would use the system temp directory. */
|
|
105
|
+
createTempDir(prefix?: string, abortSignal?: AbortSignal): Promise<Result<string, FileErrorType>>;
|
|
106
|
+
private innerTempDir;
|
|
107
|
+
/** Redirected inside the jail, for the same reason as {@link createTempDir}. */
|
|
108
|
+
createTempFile(options?: {
|
|
109
|
+
prefix?: string;
|
|
110
|
+
suffix?: string;
|
|
111
|
+
abortSignal?: AbortSignal;
|
|
112
|
+
}): Promise<Result<string, FileErrorType>>;
|
|
113
|
+
cleanup(): Promise<void>;
|
|
114
|
+
}
|
|
115
|
+
/** Where the two documents live inside a scratch directory. */
|
|
116
|
+
export declare const SCRATCH_SOURCE = "source";
|
|
117
|
+
export declare const SCRATCH_TRANSLATION = "translation";
|
|
118
|
+
export interface Scratch {
|
|
119
|
+
/** Absolute path of the scratch directory. */
|
|
120
|
+
root: string;
|
|
121
|
+
/** The confined environment the agent's tools run against. */
|
|
122
|
+
env: ExecutionEnv;
|
|
123
|
+
/** Path of the masked source, as the agent addresses it. */
|
|
124
|
+
sourcePath: string;
|
|
125
|
+
/** Path of the document the agent produces, as the agent addresses it. */
|
|
126
|
+
translationPath: string;
|
|
127
|
+
/** Whatever the agent has produced so far. */
|
|
128
|
+
readTranslation(): Promise<string>;
|
|
129
|
+
/** Removes the directory. Best effort. */
|
|
130
|
+
dispose(): Promise<void>;
|
|
131
|
+
}
|
|
132
|
+
export interface CreateScratchOptions {
|
|
133
|
+
/** Directory to create the scratch inside. */
|
|
134
|
+
parentDir: string;
|
|
135
|
+
/** A name that makes the directory recognisable in a build log. */
|
|
136
|
+
label: string;
|
|
137
|
+
/** The masked source document — never the raw one. */
|
|
138
|
+
maskedSource: string;
|
|
139
|
+
/** `.mdx` or `.md`; kept so the agent sees the extension it is writing for. */
|
|
140
|
+
extension: string;
|
|
141
|
+
}
|
|
142
|
+
export declare const createScratch: ({ parentDir, label, maskedSource, extension, }: CreateScratchOptions) => Promise<Scratch>;
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
let loaded;
|
|
4
|
+
export const loadPi = async () => {
|
|
5
|
+
loaded ??= {
|
|
6
|
+
core: await import('@earendil-works/pi-agent-core'),
|
|
7
|
+
NodeExecutionEnv: (await import('@earendil-works/pi-agent-core/node'))
|
|
8
|
+
.NodeExecutionEnv,
|
|
9
|
+
};
|
|
10
|
+
return loaded;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Confines an {@link ExecutionEnv} to one directory.
|
|
14
|
+
*
|
|
15
|
+
* Anything addressed outside it comes back `not_found` — the same answer as a
|
|
16
|
+
* path that does not exist, so the boundary does not double as an oracle for
|
|
17
|
+
* what lives beyond it.
|
|
18
|
+
*/
|
|
19
|
+
export class JailedExecutionEnv {
|
|
20
|
+
cwd;
|
|
21
|
+
root;
|
|
22
|
+
inner;
|
|
23
|
+
pi;
|
|
24
|
+
constructor({ root, inner, pi }) {
|
|
25
|
+
this.root = path.resolve(root);
|
|
26
|
+
this.cwd = this.root;
|
|
27
|
+
this.inner = inner;
|
|
28
|
+
this.pi = pi;
|
|
29
|
+
}
|
|
30
|
+
/** `not_found` for everything outside, so the jail reveals nothing about what is out there. */
|
|
31
|
+
outside(addressed) {
|
|
32
|
+
return this.pi.err(new this.pi.FileError('not_found', `No such file or directory: ${addressed}`, addressed));
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* The addressed path, or `undefined` when it leaves the jail.
|
|
36
|
+
*
|
|
37
|
+
* Two checks, because either alone has a hole: the lexical one rejects
|
|
38
|
+
* `../../etc/passwd` without touching the disk, and the symlink one rejects a
|
|
39
|
+
* path that stays inside lexically but resolves outside.
|
|
40
|
+
*/
|
|
41
|
+
async confine(target) {
|
|
42
|
+
const absolute = path.resolve(this.root, target);
|
|
43
|
+
const relative = path.relative(this.root, absolute);
|
|
44
|
+
if (relative !== '' &&
|
|
45
|
+
(relative.startsWith('..') || path.isAbsolute(relative))) {
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
// Follow symlinks on the deepest part of the path that exists. A link
|
|
49
|
+
// created inside the jail could otherwise address anything on the machine.
|
|
50
|
+
let existing = absolute;
|
|
51
|
+
for (;;) {
|
|
52
|
+
try {
|
|
53
|
+
const real = await fs.realpath(existing);
|
|
54
|
+
const realRoot = await fs.realpath(this.root);
|
|
55
|
+
const relativeReal = path.relative(realRoot, real);
|
|
56
|
+
if (relativeReal !== '' &&
|
|
57
|
+
(relativeReal.startsWith('..') || path.isAbsolute(relativeReal))) {
|
|
58
|
+
return undefined;
|
|
59
|
+
}
|
|
60
|
+
return absolute;
|
|
61
|
+
}
|
|
62
|
+
catch {
|
|
63
|
+
const parent = path.dirname(existing);
|
|
64
|
+
if (parent === existing) {
|
|
65
|
+
return absolute;
|
|
66
|
+
}
|
|
67
|
+
existing = parent;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
async withPath(target, run) {
|
|
72
|
+
const absolute = await this.confine(target);
|
|
73
|
+
return absolute ? run(absolute) : this.outside(target);
|
|
74
|
+
}
|
|
75
|
+
absolutePath(target) {
|
|
76
|
+
return this.withPath(target, (absolute) => Promise.resolve(this.pi.ok(absolute)));
|
|
77
|
+
}
|
|
78
|
+
async joinPath(parts) {
|
|
79
|
+
return this.withPath(path.join(...parts), (absolute) => Promise.resolve(this.pi.ok(absolute)));
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Refused outright.
|
|
83
|
+
*
|
|
84
|
+
* The agent is given no shell tool, so nothing should reach this. It refuses
|
|
85
|
+
* anyway: the reason there is no shell is that a shell reads any file and runs
|
|
86
|
+
* any command in the build container, and that reason does not stop being true
|
|
87
|
+
* if someone later adds a tool that uses `exec`.
|
|
88
|
+
*/
|
|
89
|
+
exec(command, options) {
|
|
90
|
+
void command;
|
|
91
|
+
void options;
|
|
92
|
+
return Promise.resolve(this.pi.err(new this.pi.ExecutionError('shell_unavailable', 'No shell is available while translating.')));
|
|
93
|
+
}
|
|
94
|
+
readTextFile(target, abortSignal) {
|
|
95
|
+
return this.withPath(target, (absolute) => this.inner.readTextFile(absolute, abortSignal));
|
|
96
|
+
}
|
|
97
|
+
readTextLines(target, options) {
|
|
98
|
+
return this.withPath(target, (absolute) => this.inner.readTextLines(absolute, options));
|
|
99
|
+
}
|
|
100
|
+
readBinaryFile(target, abortSignal) {
|
|
101
|
+
return this.withPath(target, (absolute) => this.inner.readBinaryFile(absolute, abortSignal));
|
|
102
|
+
}
|
|
103
|
+
writeFile(target, content, abortSignal) {
|
|
104
|
+
return this.withPath(target, (absolute) => this.inner.writeFile(absolute, content, abortSignal));
|
|
105
|
+
}
|
|
106
|
+
appendFile(target, content, abortSignal) {
|
|
107
|
+
return this.withPath(target, (absolute) => this.inner.appendFile(absolute, content, abortSignal));
|
|
108
|
+
}
|
|
109
|
+
async renameFile(sourcePath, destinationPath, abortSignal) {
|
|
110
|
+
const destination = await this.confine(destinationPath);
|
|
111
|
+
if (!destination) {
|
|
112
|
+
return this.outside(destinationPath);
|
|
113
|
+
}
|
|
114
|
+
return this.withPath(sourcePath, (absolute) => this.inner.renameFile(absolute, destination, abortSignal));
|
|
115
|
+
}
|
|
116
|
+
fileInfo(target, abortSignal) {
|
|
117
|
+
return this.withPath(target, (absolute) => this.inner.fileInfo(absolute, abortSignal));
|
|
118
|
+
}
|
|
119
|
+
listDir(target, abortSignal) {
|
|
120
|
+
return this.withPath(target, (absolute) => this.inner.listDir(absolute, abortSignal));
|
|
121
|
+
}
|
|
122
|
+
canonicalPath(target, abortSignal) {
|
|
123
|
+
return this.withPath(target, (absolute) => this.inner.canonicalPath(absolute, abortSignal));
|
|
124
|
+
}
|
|
125
|
+
exists(target, abortSignal) {
|
|
126
|
+
return this.withPath(target, (absolute) => this.inner.exists(absolute, abortSignal));
|
|
127
|
+
}
|
|
128
|
+
createDir(target, options) {
|
|
129
|
+
return this.withPath(target, (absolute) => this.inner.createDir(absolute, options));
|
|
130
|
+
}
|
|
131
|
+
remove(target, options) {
|
|
132
|
+
return this.withPath(target, (absolute) => this.inner.remove(absolute, options));
|
|
133
|
+
}
|
|
134
|
+
/** Redirected inside the jail: the wrapped environment would use the system temp directory. */
|
|
135
|
+
async createTempDir(prefix = 'tmp-', abortSignal) {
|
|
136
|
+
const base = path.join(this.root, '.tmp');
|
|
137
|
+
await fs.mkdir(base, { recursive: true });
|
|
138
|
+
return this.withPath(base, () => this.innerTempDir(base, prefix, abortSignal));
|
|
139
|
+
}
|
|
140
|
+
async innerTempDir(base, prefix, abortSignal) {
|
|
141
|
+
void abortSignal;
|
|
142
|
+
try {
|
|
143
|
+
return this.pi.ok(await fs.mkdtemp(path.join(base, prefix)));
|
|
144
|
+
}
|
|
145
|
+
catch (error) {
|
|
146
|
+
return this.pi.err(new this.pi.FileError('unknown', `Could not create a temporary directory: ${error instanceof Error ? error.message : String(error)}`, base));
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/** Redirected inside the jail, for the same reason as {@link createTempDir}. */
|
|
150
|
+
async createTempFile(options) {
|
|
151
|
+
const directory = await this.createTempDir('tmp-');
|
|
152
|
+
if (!directory.ok) {
|
|
153
|
+
return directory;
|
|
154
|
+
}
|
|
155
|
+
const target = path.join(directory.value, `${options?.prefix ?? ''}file${options?.suffix ?? ''}`);
|
|
156
|
+
const written = await this.inner.writeFile(target, '');
|
|
157
|
+
return written.ok ? this.pi.ok(target) : written;
|
|
158
|
+
}
|
|
159
|
+
cleanup() {
|
|
160
|
+
return this.inner.cleanup();
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
/** Where the two documents live inside a scratch directory. */
|
|
164
|
+
export const SCRATCH_SOURCE = 'source';
|
|
165
|
+
export const SCRATCH_TRANSLATION = 'translation';
|
|
166
|
+
export const createScratch = async ({ parentDir, label, maskedSource, extension, }) => {
|
|
167
|
+
const pi = await loadPi();
|
|
168
|
+
await fs.mkdir(parentDir, { recursive: true });
|
|
169
|
+
const root = await fs.mkdtemp(path.join(parentDir, `${label}-`));
|
|
170
|
+
const sourcePath = path.join(root, `${SCRATCH_SOURCE}${extension}`);
|
|
171
|
+
const translationPath = path.join(root, `${SCRATCH_TRANSLATION}${extension}`);
|
|
172
|
+
await fs.writeFile(sourcePath, maskedSource);
|
|
173
|
+
await fs.writeFile(translationPath, '');
|
|
174
|
+
const env = new JailedExecutionEnv({
|
|
175
|
+
root,
|
|
176
|
+
inner: new pi.NodeExecutionEnv({ cwd: root }),
|
|
177
|
+
pi: pi.core,
|
|
178
|
+
});
|
|
179
|
+
return {
|
|
180
|
+
root,
|
|
181
|
+
env,
|
|
182
|
+
sourcePath,
|
|
183
|
+
translationPath,
|
|
184
|
+
readTranslation: () => fs.readFile(translationPath, 'utf8'),
|
|
185
|
+
dispose: () => fs.rm(root, { recursive: true, force: true }),
|
|
186
|
+
};
|
|
187
|
+
};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { Language } from '../shared/index.ts';
|
|
2
|
+
/**
|
|
3
|
+
* The product's established translations for the terms a document uses.
|
|
4
|
+
*
|
|
5
|
+
* One implementation, because two consumers need exactly the same answer: the
|
|
6
|
+
* translator is told to use these, and the reviewer has to be told that using
|
|
7
|
+
* them is correct. When only the translator had the table, the reviewer
|
|
8
|
+
* reported the house translation of a product term as a mistranslation —
|
|
9
|
+
* measured on the corpus, that was four of the ten false reds in the first
|
|
10
|
+
* calibration, all of them one term.
|
|
11
|
+
*/
|
|
12
|
+
export interface TermPair {
|
|
13
|
+
source: string;
|
|
14
|
+
target: string;
|
|
15
|
+
}
|
|
16
|
+
export declare const TERMS_SUPPORTED_LANGUAGES: Language[];
|
|
17
|
+
export interface ResolvedTerms {
|
|
18
|
+
/** Rendered for the translator's prompt. Empty when nothing matched. */
|
|
19
|
+
text: string;
|
|
20
|
+
pairs: TermPair[];
|
|
21
|
+
}
|
|
22
|
+
export declare const resolveTerms: (sourceLang: Language, targetLang: Language, sourceContent: string) => Promise<ResolvedTerms>;
|