@gaunt-sloth/core 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/utils/displayWidth.js

@@ -23,24 +23,38 @@
  * rules below are defined over, so the two agree by construction and a sliced string's width is
  * exactly the sum of the widths of the clusters kept.
  *
- * ## What the slices expect: PLAIN text
- *
- * {@link displayWidth} is ANSI-aware and the slices are NOT, and that asymmetry is a contract
- * rather than an oversight. An escape sequence is not one cluster — the terminal swallows it
- * whole, but `ESC`, `[`, `3`, `5`, `m` segment as five, four of them printable — so the two
- * disagree on an escape-bearing string and a slice can both under-fill its budget and cut inside
- * a sequence. Feed the slices the text a user will read, and colour it afterwards; that is what
- * every caller here does, since both render surfaces map a style tag to their own escapes at the
- * very end. Making the slices ANSI-aware would change what a coloured preview line renders as,
- * which is a decision for whoever needs it and not a silent detail of this module.
- *
- * That asymmetry is also why a slice decides "does the whole string fit?" two different ways. For
- * plain text the cluster walk decides it: the widths of the clusters sum to the width of the
- * string, so walking until the budget is blown answers the question and answers it WITHOUT
- * touching the rest of the input — which is what keeps a megabyte-long preview line from being
- * measured end to end before it is cut at column 200. Only escape-bearing text is measured whole
- * first, because there the two rulers disagree and a coloured string that MEASURES as fitting must
- * be handed back whole rather than cut short by the bytes of its own escapes.
+ * ## What the slices cut: text, with its escapes carried along
+ *
+ * The slices are ANSI-aware, and they agree with {@link displayWidth} by construction. An escape
+ * sequence is not one cluster — the terminal swallows it whole, but `ESC`, `[`, `3`, `5`, `m`
+ * segment as five, four of them printable. A walk that spent budget on those printable bytes
+ * would answer a different question from the ruler it is paired with, since `string-width` strips
+ * escapes before measuring; and at a budget narrower than the content it would cut INSIDE a
+ * sequence, handing the terminal a mutilated escape.
+ *
+ * So a sequence is an indivisible token costing zero columns. It is kept whole, and it is carried
+ * along with the text it introduces, so a truncated coloured string still renders coloured. A
+ * sequence whose text is entirely cut away is dropped with that text rather than left dangling at
+ * the end of the result, where it would style nothing and leak its colour into whatever the caller
+ * appends next — an ellipsis, the next parameter, the status tag.
+ *
+ * **The result stays a genuine prefix (or suffix) of the input: no reset is appended.** Terminal
+ * state belongs to the surface that owns the line, and both render surfaces already open and close
+ * their own styling around each line they draw; an `ESC[0m` injected at the cut would close that
+ * wrapper early and un-style everything after it.
+ *
+ * Because escapes cost no budget, the clusters kept sum to the width of the string as
+ * {@link displayWidth} measures it, so the cluster walk decides "does the whole string fit?" on
+ * its own — incrementally, stopping at the budget, WITHOUT a pre-measurement of the input. That is
+ * what keeps a megabyte-long preview line from being measured end to end before it is cut at
+ * column 200, and it is why the escape-bearing case needs no separate ruler.
+ *
+ * The one input the two do not agree on is an escape sequence placed INSIDE a grapheme cluster,
+ * between a base character and its combining mark. The measurement strips the sequence and joins
+ * what is left into one cluster; the walk cannot, because the sequence has already broken the
+ * cluster in two. The walk then counts such a string WIDER than it renders, which spends budget
+ * that is not needed and can leave a slice short — never over its budget, which is the direction
+ * that matters.
  *
  * ## Why ambiguous-width characters stay NARROW — and the one place they must not
  *
@@ -75,8 +89,8 @@ const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: 'graphem
 /**
  * Terminal columns `text` occupies. Zero-width clusters (combining marks, default-ignorables)
  * count 0, wide clusters (CJK, emoji, fullwidth forms) count 2, everything else 1. ANSI escape
- * sequences are not counted, so a pre-coloured string measures as what the user sees — but the
- * slices below do not share that awareness, so do not read this as a licence to feed them one.
+ * sequences are not counted, so a pre-coloured string measures as what the user sees — and the
+ * slices below share that awareness, so a coloured string may be handed to either of them.
  */
 export function displayWidth(text) {
     return stringWidth(text);
@@ -104,22 +118,78 @@ export function firstCluster(text) {
         return segment;
     return '';
 }
-/** The clusters of `text`, in order — the only unit either slice is allowed to cut between. */
-function clusters(text) {
-    const out = [];
-    for (const { segment } of GRAPHEME_SEGMENTER.segment(text))
-        out.push(segment);
-    return out;
-}
 /**
- * Whether the whole-string measurement is the only ruler that can answer "does this fit" for
- * `text` — true exactly when it carries an escape introducer (`ESC`, or the one-byte `CSI`), the
- * two characters `string-width` itself strips on. On anything else the cluster widths sum to the
- * whole-string width, so the walk decides the same question incrementally and a pre-measurement
- * would be a second full pass over the input for nothing.
+ * The code points a sequence can begin with: `ESC` (U+001B) and the one-byte `CSI` (U+009B) — the
+ * same two characters `string-width` itself tests for before it strips.
+ */
+const ESCAPE_INTRODUCER_CODES = new Set([0x00_1b, 0x00_9b]);
+/**
+ * One ANSI escape sequence — an OSC string, or a CSI/two-character sequence — as a source pattern.
+ *
+ * This is the grammar of `ansi-regex`, which is what `strip-ansi` matches with and therefore what
+ * `string-width` removes before it measures. It is reproduced here rather than imported so the walk
+ * can never end up on a DIFFERENT copy of that package from the one `string-width` resolves: two
+ * versions in one tree would let the ruler and the walk disagree about where a sequence ends, which
+ * is the exact defect this module's ANSI-awareness exists to prevent. The spec cross-checks this
+ * pattern against `strip-ansi` itself, so a divergence fails loudly rather than silently.
+ *
+ * The OSC payload stops at the first terminator character instead of scanning ahead for one, so an
+ * unterminated OSC introducer cannot rescan the rest of the input — which is what keeps the walk
+ * linear on a long line full of half-written escapes rather than quadratic.
+ */
+const ANSI_SEQUENCE_SOURCE = [
+    '(?:\\u001B\\][^\\u0007\\u001B\\u009C]*(?:\\u0007|\\u001B\\u005C|\\u009C))',
+    '[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]',
+].join('|');
+/**
+ * The same grammar anchored with the sticky flag, so it answers "does a sequence START here?" in
+ * one step at a known index rather than searching forward for the next one anywhere in the string.
+ *
+ * Module-level, because compiling it per slice would tax the common case that never uses it. Its
+ * `lastIndex` is written immediately before every `exec`, with nothing in between, so a second walk
+ * that begins while the first is suspended cannot observe a stale position.
  */
-function needsWholeStringMeasure(text) {
-    return text.includes('\u001B') || text.includes('\u009B');
+const ANSI_SEQUENCE_AT_INDEX = new RegExp(ANSI_SEQUENCE_SOURCE, 'y');
+/**
+ * The pieces of `text` in order — whole escape sequences and whole grapheme clusters, the only
+ * units either slice is allowed to cut between.
+ *
+ * Lazy, and that is the point: the head slice stops pulling at its budget, so a megabyte-long line
+ * costs the length of the RESULT rather than the length of the input.
+ *
+ * An escape introducer is always its own cluster, because the segmentation rules break on both
+ * sides of a control character — so a sequence can only ever begin where a cluster begins, and one
+ * anchored match there settles how far it runs. The clusters it spans are then skipped. A cluster
+ * that STRADDLES the end of a sequence (a combining mark binding to the sequence's final byte)
+ * yields only the part beyond it, so the pieces always reassemble into the input exactly.
+ */
+function* widthTokens(text) {
+    let index = 0;
+    for (const { segment, index: at } of GRAPHEME_SEGMENTER.segment(text)) {
+        const end = at + segment.length;
+        if (end <= index)
+            continue; // wholly inside a sequence already yielded
+        if (at < index) {
+            // Straddles the end of that sequence: only what lies beyond it is still unyielded.
+            const rest = text.slice(index, end);
+            index = end;
+            yield { text: rest, escape: false };
+            continue;
+        }
+        if (segment.length === 1 && ESCAPE_INTRODUCER_CODES.has(segment.charCodeAt(0))) {
+            ANSI_SEQUENCE_AT_INDEX.lastIndex = at;
+            const match = ANSI_SEQUENCE_AT_INDEX.exec(text);
+            if (match !== null) {
+                index = at + match[0].length;
+                yield { text: match[0], escape: true };
+                continue;
+            }
+            // An introducer that begins no sequence falls through as an ordinary cluster. It is a
+            // control character, so it measures zero and costs no budget either way.
+        }
+        index = end;
+        yield { text: segment, escape: false };
+    }
 }
 /**
  * The longest LEADING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
@@ -146,50 +216,74 @@ export function sliceToMaxWidth(text, maxWidth) {
 }
 /**
  * The head-slice both public cuts are made of, given the ruler to measure with. The ruler is passed
- * rather than chosen here so the whole-string shortcut and the cluster walk can never end up on
- * different ones — measuring the shortcut narrow and the walk wide would hand back a string that
- * overruns the very budget the caller asked to be held to.
+ * rather than chosen here so a caller cannot end up measured by one and cut by the other — reading
+ * the budget narrow and spending it wide would hand back a string that overruns the very budget the
+ * caller asked to be held to.
+ *
+ * The input is measured ONCE, incrementally, by the walk itself: escapes cost nothing, so the
+ * clusters kept sum to what {@link displayWidth} would report for them, and "does the whole string
+ * fit?" is answered by reaching the end rather than by a separate pass over the input first.
+ *
+ * Escapes are held back until a cluster is actually kept, so a sequence whose text all falls
+ * outside the budget is dropped with it instead of trailing the result and colouring whatever the
+ * caller appends next.
  */
 function sliceHeadToWidth(text, maxWidth, measure) {
     if (maxWidth <= 0)
         return '';
-    if (needsWholeStringMeasure(text) && measure(text) <= maxWidth)
-        return text;
     let width = 0;
     let kept = '';
-    for (const { segment } of GRAPHEME_SEGMENTER.segment(text)) {
-        const clusterWidth = measure(segment);
+    let pendingEscapes = '';
+    for (const token of widthTokens(text)) {
+        if (token.escape) {
+            pendingEscapes += token.text;
+            continue;
+        }
+        const clusterWidth = measure(token.text);
         if (width + clusterWidth > maxWidth)
-            break;
+            return kept;
         width += clusterWidth;
-        kept += segment;
+        kept += pendingEscapes + token.text;
+        pendingEscapes = '';
     }
-    return kept;
+    // Every token fitted, so the answer is the input itself — returned rather than reassembled, so
+    // a caller comparing the result with what it passed in gets the identity it is testing for.
+    return text;
 }
 /**
  * The longest TRAILING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
  * the tail, lose the head. The mirror of {@link sliceToWidth}, for values whose end is the
  * informative part (a path's leaf directory).
  *
- * This one materialises the clusters: it walks backwards, and cluster boundaries are only
- * derivable from the front. Its callers pass a path or a model id, so the input is a line rather
- * than a file.
+ * This one materialises the pieces: it walks backwards, and both cluster and sequence boundaries
+ * are only derivable from the front. Its callers pass a path or a model id, so the input is a line
+ * rather than a file.
+ *
+ * Keeping the END means the escapes that OPENED a style sit in the discarded head and go with it,
+ * so a tail comes back in the terminal's default styling. Only the sequences inside the kept span
+ * are carried, which leaves the tail ending in whatever state the whole string ended in — the cut
+ * introduces no bleed of its own.
  */
 export function sliceEndToWidth(text, maxWidth) {
     if (maxWidth <= 0)
         return '';
-    if (needsWholeStringMeasure(text) && displayWidth(text) <= maxWidth)
-        return text;
-    const all = clusters(text);
+    const all = [...widthTokens(text)];
     let width = 0;
     let kept = '';
+    let pendingEscapes = '';
     for (let index = all.length - 1; index >= 0; index--) {
-        const clusterWidth = displayWidth(all[index]);
+        const token = all[index];
+        if (token.escape) {
+            pendingEscapes = token.text + pendingEscapes;
+            continue;
+        }
+        const clusterWidth = displayWidth(token.text);
         if (width + clusterWidth > maxWidth)
-            break;
+            return kept;
         width += clusterWidth;
-        kept = all[index] + kept;
+        kept = token.text + pendingEscapes + kept;
+        pendingEscapes = '';
     }
-    return kept;
+    return text;
 }
 //# sourceMappingURL=displayWidth.js.map

package/dist/utils/displayWidth.js.map

@@ -1 +1 @@
-{"version":3,"file":"displayWidth.js","sourceRoot":"","sources":["../../src/utils/displayWidth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"displayWidth.js","sourceRoot":"","sources":["../../src/utils/displayWidth.ts"],"names":[],"mappings":"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"}

package/dist/utils/llmUtils.d.ts

@@ -32,7 +32,7 @@ export declare function readCodePrompt(config: PromptReadConfig): string;
 export declare function readExecPrompt(config: PromptReadConfig): string;
 /**
  * GS2-79 — the SINGLE place a command's mode prompt is chosen, for every site that composes a
- * system prompt via {@link buildSystemMessages}: both agent backends and the subagent profiles.
+ * system prompt via {@link buildSystemMessages}: the agent and the subagent profiles.
  *
  * It exists because the selection used to be an inline three-branch ternary copied to each of
  * those sites, and a command missing from one copy is silently served the CHAT prompt — the

package/dist/utils/llmUtils.js

@@ -117,7 +117,7 @@ export function readExecPrompt(config) {
 }
 /**
  * GS2-79 — the SINGLE place a command's mode prompt is chosen, for every site that composes a
- * system prompt via {@link buildSystemMessages}: both agent backends and the subagent profiles.
+ * system prompt via {@link buildSystemMessages}: the agent and the subagent profiles.
  *
  * It exists because the selection used to be an inline three-branch ternary copied to each of
  * those sites, and a command missing from one copy is silently served the CHAT prompt — the

package/dist/utils/systemPromptNotes.d.ts

@@ -93,9 +93,9 @@ export interface CommitCoAuthor {
  * it literally (the overwhelmingly common case, and a literal name is what makes the instruction
  * actionable); when it is not, the note names no tool, keeps both prohibitions and the file form,
  * and supplies the compliant path that remains: do not commit, and hand the message back to the
- * user. That branch states no availability claim of its own — the backends read the same
- * `filesystem` value but register filesystem tools differently, so a note asserting "you have no
- * file-writing tool" could be flatly false on one of them.
+ * user. That branch states no availability claim of its own — registering filesystem tools is the
+ * agent's decision, made from the same `filesystem` value, so a note asserting "you have no
+ * file-writing tool" could be flatly false.
  *
  * The note's prose carries **no backtick and no other markup** — including no angle-bracket
  * placeholder: it is the one piece of guidance whose subject is how to write a commit message, so

package/dist/utils/systemPromptNotes.js

@@ -117,9 +117,9 @@ export function appendCwdNote(systemPrompt, cwd) {
  * it literally (the overwhelmingly common case, and a literal name is what makes the instruction
  * actionable); when it is not, the note names no tool, keeps both prohibitions and the file form,
  * and supplies the compliant path that remains: do not commit, and hand the message back to the
- * user. That branch states no availability claim of its own — the backends read the same
- * `filesystem` value but register filesystem tools differently, so a note asserting "you have no
- * file-writing tool" could be flatly false on one of them.
+ * user. That branch states no availability claim of its own — registering filesystem tools is the
+ * agent's decision, made from the same `filesystem` value, so a note asserting "you have no
+ * file-writing tool" could be flatly false.
  *
  * The note's prose carries **no backtick and no other markup** — including no angle-bracket
  * placeholder: it is the one piece of guidance whose subject is how to write a commit message, so

package/dist/utils/vertexaiUtils.js

@@ -1,3 +1,4 @@
+import { env } from '#src/utils/systemUtils.js';
 export function isVertexGoogleLlm(llm) {
     if (!llm || typeof llm !== 'object') {
         return false;
@@ -70,12 +71,110 @@ const VERTEX_AUTH_GUIDANCE = {
         'Check the one this session is configured for — a Google AI Studio key is not valid for ' +
         'Vertex AI endpoints.',
 };
+/**
+ * The longest value still treated as a filesystem path. 260 is Windows' classic `MAX_PATH`, which is
+ * a defensible ceiling for a path and sits an order of magnitude below any credential: the deepest
+ * realistic ADC path — a CI runner's temp directory plus
+ * `application_default_credentials.json` — is around 120 characters, while a service-account key is
+ * ~1700 as JSON and ~2300 base64-encoded. Nothing has to land in the gap for the test to be useful.
+ */
+const MAX_CREDENTIAL_PATH_LENGTH = 260;
+/**
+ * Whether a value is the credential ITSELF rather than a path to one.
+ *
+ * Deliberately tested by SIZE first rather than by shape. The shape test alone (`{`) catches a
+ * pasted JSON key and misses the base64 form that CI secret stores hand out, and widening it one
+ * encoding at a time only ever covers the last spelling somebody thought of — the value is
+ * attacker-irrelevant but user-supplied and its formats are open-ended. Length closes the class
+ * because every credential is enormous next to every path. The shape test is kept alongside it for
+ * the short, hand-trimmed JSON that a size test alone would let through.
+ */
+function isCredentialContent(value) {
+    return value.length > MAX_CREDENTIAL_PATH_LENGTH || value.trimStart().startsWith('{');
+}
+/**
+ * Where an ADC session's credentials are being read from when an environment variable names a file,
+ * and the spelling of the variable that named it — `undefined` when no such variable is in play.
+ *
+ * THIS IS THE ONE ENVIRONMENT READ IN THIS FILE AND IT IS DELIBERATE, so read it against the
+ * comment on {@link vertexAuthMode} rather than as a contradiction of it. That function decides
+ * WHICH credential is in use and must keep doing so from the constructed client alone. This one
+ * decides nothing: the session has already been classified as ADC from the client, and the
+ * environment is consulted only to compose the DIAGNOSTIC SENTENCE for it. Read-only, through the
+ * `systemUtils` accessor like every other environment read in this package.
+ *
+ * It is not client-derived because there is nothing client-derived to be had. Measured on
+ * google-auth-library 10.9.1: `GoogleAuth.keyFilename` is populated only from constructor options,
+ * so on a Vertex client it is `undefined` both with and without the variable set, and stays
+ * `undefined` after a resolution attempt. The only artifact a successful resolution leaves behind is
+ * `jsonContent` — the parsed key file, which holds the private key and must never be printed.
+ *
+ * Mirrors `googleauth.js` rather than reinventing it: both spellings, upper case first, and an empty
+ * value falls through to the well-known file instead of counting as set.
+ */
+function adcCredentialFileFromEnvironment() {
+    for (const variable of ['GOOGLE_APPLICATION_CREDENTIALS', 'google_application_credentials']) {
+        const path = env[variable];
+        if (!path) {
+            continue;
+        }
+        // First non-empty wins, exactly as the library's `||` does — so a value that is credential
+        // CONTENT rather than a path ends the search rather than falling through to the other spelling.
+        //
+        // Pasting the service-account key into the variable instead of writing it to a file is a common
+        // CI misconfiguration, and such a session must NOT be described below. There is no file for the
+        // message to point at, so naming one would be exactly the kind of claim-that-does-not-hold this
+        // hint exists to avoid; and the value is a private key, while this message also reaches the log
+        // stream and debug dumps. It falls back to the pinned `adc` sentence, which asserts nothing
+        // about where the credentials came from.
+        return isCredentialContent(path) ? undefined : { variable, path };
+    }
+    return undefined;
+}
+/**
+ * The remedy for an ADC session whose credentials come from a file named in the environment.
+ *
+ * The diagnosis is the same as the plain `adc` one and is CORRECT — this really is ADC. What
+ * differs is that the plain remedy is inert here: `google-auth-library` resolves this variable
+ * before it reads the well-known file, so `gcloud auth application-default login` writes a file
+ * this session never opens, reports success, and leaves the failure exactly where it was. Naming
+ * the command anyway is the point — the reader has usually just run it.
+ */
+function adcFromEnvironmentGuidance(variable, path) {
+    return ('This session authenticates through Application Default Credentials, and those credentials ' +
+        'come from `' +
+        variable +
+        '` in your environment, which points at `' +
+        path +
+        '`. That variable is resolved BEFORE the well-known credentials file, so ' +
+        '`gcloud auth application-default login` writes a file this session never reads and the ' +
+        'failure survives it. Repair or replace the credentials in the file above, or unset ' +
+        '`' +
+        variable +
+        '` so the well-known Application Default Credentials file is used instead. ' +
+        'No API key is in use — a `type: vertexai` config ignores any `GOOGLE_API_KEY` in your ' +
+        'environment, so unsetting that will not help here.');
+}
+/**
+ * The sentence for a classified session. Only the ADC branch is refined further, and only into the
+ * one sub-case whose remedy would otherwise be inert; every other mode returns its pinned string
+ * unchanged.
+ */
+function vertexAuthGuidance(mode) {
+    if (mode === 'adc') {
+        const fromEnvironment = adcCredentialFileFromEnvironment();
+        if (fromEnvironment) {
+            return adcFromEnvironmentGuidance(fromEnvironment.variable, fromEnvironment.path);
+        }
+    }
+    return VERTEX_AUTH_GUIDANCE[mode];
+}
 export function enhanceVertexUnauthorizedMessage(originalMessage, llm) {
     if (!isVertexGoogleLlm(llm) || !VERTEX_AUTH_ERROR_PATTERN.test(originalMessage)) {
         return originalMessage;
     }
     return (`${originalMessage}\n\n` +
         'Vertex AI authentication failed. ' +
-        `${VERTEX_AUTH_GUIDANCE[vertexAuthMode(llm)]}\n`);
+        `${vertexAuthGuidance(vertexAuthMode(llm))}\n`);
 }
 //# sourceMappingURL=vertexaiUtils.js.map

package/dist/utils/vertexaiUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"vertexaiUtils.js","sourceRoot":"","sources":["../../src/utils/vertexaiUtils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,GAA6B,CAAC;IAC5C,OAAO,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC;AACnC,CAAC;AAED,4DAA4D;AAC5D,gEAAgE;AAChE,gFAAgF;AAChF,qFAAqF;AACrF,MAAM,yBAAyB,GAAG,4DAA4D,CAAC;AAY/F;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,GAAY;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GACV,GAGD,EAAE,SAAS,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,UAAU,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACjE,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACrC,OAAO,gBAAgB,CAAC;QAC1B,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAmC;IAC3D,MAAM,EACJ,oFAAoF;QACpF,wEAAwE;QACxE,4FAA4F;QAC5F,0FAA0F;QAC1F,4FAA4F;QAC5F,6CAA6C;IAC/C,cAAc,EACZ,6FAA6F;QAC7F,6FAA6F;QAC7F,4DAA4D;QAC5D,6FAA6F;QAC7F,eAAe;IACjB,GAAG,EACD,8FAA8F;QAC9F,+CAA+C;QAC/C,wFAAwF;QACxF,oDAAoD;IACtD,OAAO,EACL,8FAA8F;QAC9F,6FAA6F;QAC7F,yFAAyF;QACzF,yFAAyF;QACzF,sBAAsB;CACzB,CAAC;AAEF,MAAM,UAAU,gCAAgC,CAAC,eAAuB,EAAE,GAAY;IACpF,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;QAChF,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,OAAO,CACL,GAAG,eAAe,MAAM;QACxB,mCAAmC;QACnC,GAAG,oBAAoB,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,CACjD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"vertexaiUtils.js","sourceRoot":"","sources":["../../src/utils/vertexaiUtils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaunt-sloth/core",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.4",
   "description": "Core utilities and types for Gaunt Sloth",
   "license": "MIT",
   "author": "Andrew Kondratev",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@langchain/core": "^1.2.9",
-    "@langchain/langgraph": "^1.4.12",
+    "@langchain/langgraph": "^1.4.13",
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
     "langchain": "^1.5.10",
@@ -89,6 +89,7 @@
   "scripts": {
     "build": "tsc",
     "schema:generate": "node scripts/generate-config-schema.mjs",
-    "surface:generate": "node scripts/generate-type-surface.mjs"
+    "surface:generate": "node scripts/generate-type-surface.mjs",
+    "value-surface:generate": "node scripts/generate-value-surface.mjs"
   }
 }