@jitsusama/agentic-harness.core 0.1.0

package/dist/refs/lookup.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Refs lookup: read access into the registry plus parsing
+ * helpers and URL building.
+ *
+ * `parseRef` is for short strings (an alias value, a single
+ * link in a frontmatter scalar): it returns the first match
+ * across registered types. `parseAllRefs` is for long
+ * bodies of prose: it returns every match.
+ */
+import type { Ref, RefType } from "./types.js";
+/** Look up a registered type by its identifier. */
+export declare function getRefType(type: string): RefType | undefined;
+/** Snapshot of every registered type in registration order. */
+export declare function listRefTypes(): RefType[];
+/**
+ * Parse a short text fragment as a single ref. Returns the
+ * first match across registered types, walking the registry
+ * in registration order. Returns `undefined` when nothing
+ * matches.
+ *
+ * Use this for inputs the caller believes contains one ref
+ * (an alias scalar, a CLI argument, a single line of text).
+ * For longer prose use `parseAllRefs`.
+ */
+export declare function parseRef(text: string): Ref | undefined;
+/**
+ * Parse a longer body of text and return every ref found
+ * across registered types. Duplicate `{type, value}` pairs
+ * are dropped. Order follows registration order across
+ * types, then per-type match order within each.
+ */
+export declare function parseAllRefs(text: string): Ref[];
+/**
+ * Build a canonical URL from a structured ref. Returns
+ * `undefined` when the ref's type has no `url` function or
+ * when the value cannot be encoded.
+ */
+export declare function urlForRef(ref: Ref): string | undefined;
+/**
+ * Why this ref has no URL, or nothing when it has one.
+ *
+ * The counterpart to {@link urlForRef}, kept separate for the same
+ * reason the front-matter parser and its explainer are separate: most
+ * callers want a link or nothing, and only the one rendering a list a
+ * person reads has to account for the gap.
+ *
+ * Silence here is not the same as a missing link. A type with no URL
+ * form at all, like a person identity, is not failing to encode
+ * anything, so it says nothing and the caller shows no link and no
+ * complaint. A type that could encode and did not is where the reason
+ * comes from.
+ */
+export declare function whyRefHasNoUrl(ref: Ref): string | undefined;

package/dist/refs/lookup.js

@@ -0,0 +1,102 @@
+/**
+ * Refs lookup: read access into the registry plus parsing
+ * helpers and URL building.
+ *
+ * `parseRef` is for short strings (an alias value, a single
+ * link in a frontmatter scalar): it returns the first match
+ * across registered types. `parseAllRefs` is for long
+ * bodies of prose: it returns every match.
+ */
+import { get, list, parseAll } from "../internal/refs/registry.js";
+/** Look up a registered type by its identifier. */
+export function getRefType(type) {
+    return get(type);
+}
+/** Snapshot of every registered type in registration order. */
+export function listRefTypes() {
+    return list();
+}
+/**
+ * Parse a short text fragment as a single ref. Returns the
+ * first match across registered types, walking the registry
+ * in registration order. Returns `undefined` when nothing
+ * matches.
+ *
+ * Use this for inputs the caller believes contains one ref
+ * (an alias scalar, a CLI argument, a single line of text).
+ * For longer prose use `parseAllRefs`.
+ */
+export function parseRef(text) {
+    for (const rt of list()) {
+        const matches = rt.matchAll(text);
+        if (matches.length > 0)
+            return { type: rt.type, value: matches[0] };
+    }
+    return undefined;
+}
+/**
+ * Parse a longer body of text and return every ref found
+ * across registered types. Duplicate `{type, value}` pairs
+ * are dropped. Order follows registration order across
+ * types, then per-type match order within each.
+ */
+export function parseAllRefs(text) {
+    return parseAll(text);
+}
+/**
+ * Build a canonical URL from a structured ref. Returns
+ * `undefined` when the ref's type has no `url` function or
+ * when the value cannot be encoded.
+ */
+export function urlForRef(ref) {
+    const encoded = get(ref.type)?.url?.(ref.value);
+    if (encoded !== undefined)
+        return encoded;
+    // A value that is already a link is its own link. Sweeping the live
+    // store turned up refs under types nobody registered, several of
+    // them holding a whole `https://` URL and rendering as no link at
+    // all, which is absurd: `url: https://...` had a link in it the
+    // entire time. This is the identity function rather than an
+    // inference, so it invents nothing, and it runs second so a
+    // registered type's own encoding always wins.
+    return absoluteUrl(ref.value);
+}
+/** The value itself, when the value is already an http or https URL. */
+function absoluteUrl(value) {
+    if (!/^https?:\/\//.test(value))
+        return undefined;
+    try {
+        return new URL(value).href === "" ? undefined : value;
+    }
+    catch {
+        // Starts like a URL and is not one. Nothing to hand back, and
+        // nothing worth complaining about either: an unregistered type
+        // never promised a link.
+        return undefined;
+    }
+}
+/**
+ * Why this ref has no URL, or nothing when it has one.
+ *
+ * The counterpart to {@link urlForRef}, kept separate for the same
+ * reason the front-matter parser and its explainer are separate: most
+ * callers want a link or nothing, and only the one rendering a list a
+ * person reads has to account for the gap.
+ *
+ * Silence here is not the same as a missing link. A type with no URL
+ * form at all, like a person identity, is not failing to encode
+ * anything, so it says nothing and the caller shows no link and no
+ * complaint. A type that could encode and did not is where the reason
+ * comes from.
+ */
+export function whyRefHasNoUrl(ref) {
+    const type = get(ref.type);
+    if (type?.url === undefined)
+        return undefined;
+    if (type.url(ref.value) !== undefined)
+        return undefined;
+    return (type.whyNoUrl?.(ref.value) ??
+        // A type that can decline without explaining itself. Better than
+        // nothing, and it names the type so somebody knows where to look.
+        `"${ref.value}" is not a value the ${ref.type} type can turn into a link.`);
+}

package/dist/refs/register.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Refs registration: add, remove and seed ref types in the
+ * package-wide registry.
+ *
+ * The registry is module-level; a single `RefType` per
+ * identifier wins. Re-registering the same identifier
+ * replaces the previous definition. The refs library does
+ * not auto-register the built-ins: callers (e.g. the quest
+ * extension) call `registerBuiltinRefTypes()` on activate
+ * to opt in.
+ */
+import type { RefType } from "./types.js";
+/**
+ * Register a ref type. Overwrites any previously registered
+ * type with the same `type` identifier.
+ */
+export declare function registerRefType(refType: RefType): void;
+/**
+ * Remove a ref type from the registry. Idempotent: removing
+ * an absent type is a no-op.
+ */
+export declare function unregisterRefType(type: string): void;
+/**
+ * Seed the registry with the built-in ref types:
+ * `github-issue`, `github-pr`, `github-repo`,
+ * `slack-message` and `slack-thread`. Idempotent;
+ * re-registers each definition on every call.
+ */
+export declare function registerBuiltinRefTypes(): void;
+/**
+ * Empty the registry. Intended for tests and `/reload`
+ * semantics; not for normal extension code.
+ */
+export declare function clearRefTypes(): void;

package/dist/refs/register.js

@@ -0,0 +1,44 @@
+/**
+ * Refs registration: add, remove and seed ref types in the
+ * package-wide registry.
+ *
+ * The registry is module-level; a single `RefType` per
+ * identifier wins. Re-registering the same identifier
+ * replaces the previous definition. The refs library does
+ * not auto-register the built-ins: callers (e.g. the quest
+ * extension) call `registerBuiltinRefTypes()` on activate
+ * to opt in.
+ */
+import { BUILTIN_REF_TYPES } from "../internal/refs/builtins.js";
+import { clear, register, unregister } from "../internal/refs/registry.js";
+/**
+ * Register a ref type. Overwrites any previously registered
+ * type with the same `type` identifier.
+ */
+export function registerRefType(refType) {
+    register(refType);
+}
+/**
+ * Remove a ref type from the registry. Idempotent: removing
+ * an absent type is a no-op.
+ */
+export function unregisterRefType(type) {
+    unregister(type);
+}
+/**
+ * Seed the registry with the built-in ref types:
+ * `github-issue`, `github-pr`, `github-repo`,
+ * `slack-message` and `slack-thread`. Idempotent;
+ * re-registers each definition on every call.
+ */
+export function registerBuiltinRefTypes() {
+    for (const rt of BUILTIN_REF_TYPES)
+        register(rt);
+}
+/**
+ * Empty the registry. Intended for tests and `/reload`
+ * semantics; not for normal extension code.
+ */
+export function clearRefTypes() {
+    clear();
+}

package/dist/refs/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for the refs library.
+ *
+ * A `Ref` is a structured reference to an external system
+ * entity (a GitHub issue, a Slack thread, a Graphite PR).
+ * A `RefType` knows how to recognise its own surface forms
+ * in text and how to build a canonical URL from a stored
+ * value.
+ *
+ * The refs library is pluggable: consumers register their
+ * own types alongside the built-ins. The quest extension
+ * uses it to extract inline references from prose and to
+ * resolve aliases in frontmatter; downstream packages can
+ * register custom types (e.g. company-specific URL
+ * schemes) without forking the library.
+ */
+/** A structured reference to an external entity. */
+export interface Ref {
+    /**
+     * The ref type identifier registered via
+     * `registerRefType`, e.g. `"github-issue"`,
+     * `"slack-thread"`.
+     */
+    type: string;
+    /**
+     * The canonical value for this ref. Format is
+     * type-specific (e.g. `"shop/world#47281"` for
+     * `github-issue`, a Slack archive URL fragment for
+     * `slack-thread`). The type's `matchAll` produces this
+     * value; its `url` reverses it.
+     */
+    value: string;
+}
+/** Definition of a ref type. */
+export interface RefType {
+    /**
+     * Unique identifier for this type. Used as the
+     * discriminator in `Ref.type` and the key in the
+     * registry. Convention is kebab-case with the system
+     * prefix, e.g. `"github-issue"`, `"slack-thread"`.
+     */
+    type: string;
+    /**
+     * Find every canonical value of this type in the given
+     * text. Returns an empty array when the text contains
+     * no matches. Implementations should be tolerant of
+     * arbitrary input: HTML, markdown prose, frontmatter
+     * scalars, single short strings.
+     */
+    matchAll(text: string): string[];
+    /**
+     * Build a canonical URL from a stored value. Optional:
+     * types that have no clean URL form (e.g. a person
+     * identity) omit this. Returns `undefined` when the
+     * value cannot be encoded.
+     */
+    url?(value: string): string | undefined;
+    /**
+     * Why {@link url} could not encode this value, or nothing when it
+     * could.
+     *
+     * A separate method rather than a richer return from `url`, for the
+     * reason the same split exists over quest front matter: almost
+     * every caller wants a URL or nothing, and making all of them
+     * unwrap a result to get a string they already had would be a worse
+     * trade than one extra optional method here.
+     *
+     * It exists because a silent `undefined` is how 621 stored Slack
+     * refs came to produce no link with nothing anywhere saying so. The
+     * value was fine, the type was fine, and the two simply disagreed
+     * about the shape: written from API data as `CHANNEL/TIMESTAMP`,
+     * read back by a pattern wanting `workspace/CHANNEL/pTIMESTAMP`. A
+     * reason naming both shapes turns that from an invisible nothing
+     * into a thing somebody can fix.
+     *
+     * Implement it wherever `url` can decline. A type without it is
+     * saying its values never fail to encode, which is true of a type
+     * that has no URL form at all.
+     */
+    whyNoUrl?(value: string): string | undefined;
+}

package/dist/refs/types.js

@@ -0,0 +1,17 @@
+/**
+ * Types for the refs library.
+ *
+ * A `Ref` is a structured reference to an external system
+ * entity (a GitHub issue, a Slack thread, a Graphite PR).
+ * A `RefType` knows how to recognise its own surface forms
+ * in text and how to build a canonical URL from a stored
+ * value.
+ *
+ * The refs library is pluggable: consumers register their
+ * own types alongside the built-ins. The quest extension
+ * uses it to extract inline references from prose and to
+ * resolve aliases in frontmatter; downstream packages can
+ * register custom types (e.g. company-specific URL
+ * schemes) without forking the library.
+ */
+export {};

package/dist/remote/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of the remote library.
+ *
+ * Naming a git remote to a person. Its own module for the reason
+ * `lib/exec` is: both `lib/review` and `lib/work` show a remote in
+ * their refusals, and neither owns the question of what a remote may
+ * safely say.
+ */
+export { withoutCredentials } from "./name.js";

package/dist/remote/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public surface of the remote library.
+ *
+ * Naming a git remote to a person. Its own module for the reason
+ * `lib/exec` is: both `lib/review` and `lib/work` show a remote in
+ * their refusals, and neither owns the question of what a remote may
+ * safely say.
+ */
+export { withoutCredentials } from "./name.js";

package/dist/remote/name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A git remote URL as it is safe to show a person.
+ */
+/**
+ * A remote URL with its credential removed, if it carried one.
+ *
+ * The whole userinfo goes, not just the password. A token is accepted
+ * in either position, so `token@host` is as much a secret as
+ * `user:token@host`, and keeping the user would leak exactly the form
+ * that looks harmless. What is lost is `git@` on an ssh URL, which
+ * names no one and is worth less than the rule being simple.
+ *
+ * Only URLs with a scheme. An scp-style remote, `git@host:path`, has
+ * no userinfo field to speak of and no way to carry a password, so it
+ * is left as written rather than rewritten into something the person
+ * reading it never typed.
+ *
+ * For display only. The remote a fetch is run against keeps whatever
+ * it needs to authenticate, because taking the credential out of that
+ * one would not hide it, it would break it.
+ */
+export declare function withoutCredentials(remoteUrl: string): string;

package/dist/remote/name.js

@@ -0,0 +1,30 @@
+/**
+ * A git remote URL as it is safe to show a person.
+ */
+/**
+ * The userinfo of a URL: everything between the scheme and the `@`
+ * that introduces the host. It cannot cross a slash, so an at sign
+ * later in the path is part of the path.
+ */
+const USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i;
+/**
+ * A remote URL with its credential removed, if it carried one.
+ *
+ * The whole userinfo goes, not just the password. A token is accepted
+ * in either position, so `token@host` is as much a secret as
+ * `user:token@host`, and keeping the user would leak exactly the form
+ * that looks harmless. What is lost is `git@` on an ssh URL, which
+ * names no one and is worth less than the rule being simple.
+ *
+ * Only URLs with a scheme. An scp-style remote, `git@host:path`, has
+ * no userinfo field to speak of and no way to carry a password, so it
+ * is left as written rather than rewritten into something the person
+ * reading it never typed.
+ *
+ * For display only. The remote a fetch is run against keeps whatever
+ * it needs to authenticate, because taking the credential out of that
+ * one would not hide it, it would break it.
+ */
+export function withoutCredentials(remoteUrl) {
+    return remoteUrl.replace(USERINFO, "$1");
+}

package/dist/result/cite.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Deciding whether an answer needs a handle, and saying so.
+ *
+ * The rule is one sentence: cite a handle exactly when the stored
+ * payload holds more than the inline view shows. Both halves of
+ * that matter. Citing always would put a line of machinery on
+ * answers that are already complete, and train a reader to skip
+ * it, which is the same as not printing it. Citing only when asked
+ * would require the caller to know in advance that the page was
+ * enormous, and that is precisely the thing they called to find
+ * out.
+ *
+ * This lives in one place because every family needs the same
+ * decision and none of them should be making it. A tool that
+ * decided for itself would drift: one would cite at a kilobyte,
+ * another at a megabyte, a third would forget, and the caller
+ * would have to learn each one's habits instead of the rule.
+ */
+import type { ResultStore } from "./store.js";
+/** What a family knows about the answer it is about to give. */
+export interface Citable<T> {
+    /** The whole payload, as a structure a query can walk. */
+    readonly payload: T;
+    /** The bounded text the caller reads first. */
+    readonly view: string;
+    /**
+     * How much of the payload the view actually shows, and how much
+     * there is. When these agree the view is the whole truth and no
+     * handle is cited.
+     */
+    readonly shown: number;
+    readonly total: number;
+    /** What the units are, for a sentence a human can read. */
+    readonly unit: string;
+    /**
+     * What the payload holds, when that is a different unit from the
+     * one being counted.
+     *
+     * A listing counts lines, because lines are what the reader can
+     * see and count for themselves, but what gets stored is the
+     * records those lines were rendered from. Without this the
+     * citation says all 797 lines are stored, which is false, and the
+     * family has to append a sentence taking it back. Driving Slack
+     * for real is what surfaced it: the answer claimed lines were
+     * stored and then said the payload was not lines, one after the
+     * other.
+     */
+    readonly stored?: {
+        readonly count?: number;
+        readonly unit: string;
+    };
+    /**
+     * Whether the view omits part of the payload for reasons of its
+     * own, with the counts agreeing.
+     *
+     * The counts answer "did the budget cut this", which is not the
+     * same question as "is this all of it". An audit prints five
+     * elements per rule and a count of the rest: every line it
+     * intended to write got written, so shown equals total, and
+     * without this the handle nobody needs more is the only one
+     * offered while the answer hiding eight thousand elements offers
+     * none.
+     */
+    readonly elided?: boolean;
+}
+/** An answer, with a handle when there is more to be had. */
+export interface Cited {
+    /** The text to return: the view, and the citation when there is one. */
+    readonly text: string;
+    /** The handle, when the payload was stored. */
+    readonly handle?: string;
+    /** Where the payload landed, when it was stored. */
+    readonly path?: string;
+}
+/**
+ * Store a payload and cite it when the view does not show all of
+ * it.
+ *
+ * A failure to store is reported rather than thrown, and never
+ * costs the caller their answer: the view is what they asked for,
+ * the handle is a convenience, and losing a convenience is not
+ * worth losing a page read over.
+ */
+export declare function cite<T>(store: ResultStore, answer: Citable<T>): Cited;

package/dist/result/cite.js

@@ -0,0 +1,127 @@
+/**
+ * Deciding whether an answer needs a handle, and saying so.
+ *
+ * The rule is one sentence: cite a handle exactly when the stored
+ * payload holds more than the inline view shows. Both halves of
+ * that matter. Citing always would put a line of machinery on
+ * answers that are already complete, and train a reader to skip
+ * it, which is the same as not printing it. Citing only when asked
+ * would require the caller to know in advance that the page was
+ * enormous, and that is precisely the thing they called to find
+ * out.
+ *
+ * This lives in one place because every family needs the same
+ * decision and none of them should be making it. A tool that
+ * decided for itself would drift: one would cite at a kilobyte,
+ * another at a megabyte, a third would forget, and the caller
+ * would have to learn each one's habits instead of the rule.
+ */
+import { count } from "./counts.js";
+import { summarizeJson } from "./digest.js";
+import { queryTool } from "./follow.js";
+/**
+ * Store a payload and cite it when the view does not show all of
+ * it.
+ *
+ * A failure to store is reported rather than thrown, and never
+ * costs the caller their answer: the view is what they asked for,
+ * the handle is a convenience, and losing a convenience is not
+ * worth losing a page read over.
+ */
+export function cite(store, answer) {
+    if (answer.shown >= answer.total && !answer.elided) {
+        return { text: answer.view };
+    }
+    let stored;
+    try {
+        stored = store.put(JSON.stringify(answer.payload));
+    }
+    catch (err) {
+        return {
+            text: `${answer.view}\n\n${unstorable(answer, err)}`,
+        };
+    }
+    const digest = summarizeJson(answer.payload);
+    return {
+        text: `${answer.view}\n\n${citation(answer, stored.handle, digest)}`,
+        handle: stored.handle,
+        path: stored.path,
+    };
+}
+/**
+ * Whether a query could pick something smaller out of this.
+ *
+ * Objects and arrays have parts to name; a string or a number is
+ * one thing, and every expression that matches it matches the
+ * whole of it.
+ */
+function hasFields(payload) {
+    return typeof payload === "object" && payload !== null;
+}
+/** The sentence that turns a handle into something usable. */
+function citation(answer, handle, digest) {
+    const held = count(answer.total);
+    const seen = count(answer.shown);
+    const tool = queryTool();
+    const rest = tool === undefined
+        ? // Naming a tool that is not loaded is worse than saying
+            // nothing: it promises the rest of the data is one call
+            // away. The shape still helps a reader decide whether it
+            // is worth following up on.
+            `No tool in this session can read a handle, so this one ` +
+                `cannot be followed. Shape: ${digest}`
+        : hasFields(answer.payload)
+            ? `Query it with ${tool}, projecting the fields you want ` +
+                `rather than whole records. Shape: ${digest}`
+            : // Advice that cannot be followed is worse than none.
+                // Reading the body of a stylesheet stored 211,762
+                // bytes of minified css and said to project the
+                // fields wanted rather than whole records. There are
+                // no fields on a string, and the one expression that
+                // matches it returns every byte, so the advice led
+                // back into the dump the bound had just avoided.
+                `It has no fields to project, so ${tool} can only ` +
+                    `return the whole of it at once. Shape: ${digest}`;
+    if (answer.elided && answer.shown >= answer.total) {
+        // Nothing was cut, so there is no shortfall in lines to report.
+        // Saying "renders 12 of 12 lines" next to a handle would invite
+        // the reader to conclude they had already seen everything.
+        const what = answer.stored?.count === undefined
+            ? `The whole ${answer.stored?.unit ?? "payload"}`
+            : `All ${count(answer.stored.count)} ${answer.stored.unit}`;
+        return (`${what} are stored under handle ${handle}; this view lists ` +
+            `only some of them. ${rest}`);
+    }
+    if (answer.stored !== undefined) {
+        // Two different counts, said once each: what is on disk, and how
+        // much of the rendering the reader is looking at.
+        if (answer.stored.count === undefined) {
+            // Nothing countable was identified, so the payload is described
+            // rather than counted. Inventing a count of one would read as a
+            // single record and send a caller looking for it.
+            return (`The whole ${answer.stored.unit} is stored under handle ` +
+                `${handle}, of which this answer renders ${seen} of ` +
+                `${held} ${answer.unit}. ${rest}`);
+        }
+        const kept = count(answer.stored.count);
+        return (`All ${kept} ${answer.stored.unit} are stored under handle ` +
+            `${handle}, of which this answer renders ${seen} of ` +
+            `${held} ${answer.unit}. ${rest}`);
+    }
+    return (`All ${held} ${answer.unit} are stored under handle ${handle}; ` +
+        `this answer shows ${seen}. ${rest}`);
+}
+/**
+ * Say that the rest is unreachable, rather than implying it is
+ * merely absent.
+ *
+ * A caller told nothing would reasonably assume the view was
+ * everything and reason from a fraction of the data.
+ */
+function unstorable(answer, err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return (`This answer shows ${count(answer.shown)} of ` +
+        `${count(answer.total)} ${answer.unit}. The remainder ` +
+        `could not be stored (${why}), so it is not retrievable: narrow the ` +
+        `call to see the rest.`);
+}

package/dist/result/counts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Writing a number down the same way everywhere.
+ *
+ * Citations are read by a language model and pinned by tests, and
+ * both want one answer. `toLocaleString` gives the machine's
+ * answer: the same count reads as 18,004 here and 18.004 on a
+ * runner configured for German, where a model has every reason to
+ * take it for eighteen and a bit.
+ *
+ * Grouped by hand rather than with an explicit locale, because
+ * locale data is a dependency of the runtime and this is not worth
+ * one.
+ */
+/** A whole number, grouped in threes with commas. */
+export declare function count(value: number): string;

package/dist/result/counts.js

@@ -0,0 +1,17 @@
+/**
+ * Writing a number down the same way everywhere.
+ *
+ * Citations are read by a language model and pinned by tests, and
+ * both want one answer. `toLocaleString` gives the machine's
+ * answer: the same count reads as 18,004 here and 18.004 on a
+ * runner configured for German, where a model has every reason to
+ * take it for eighteen and a bit.
+ *
+ * Grouped by hand rather than with an explicit locale, because
+ * locale data is a dependency of the runtime and this is not worth
+ * one.
+ */
+/** A whole number, grouped in threes with commas. */
+export function count(value) {
+    return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}