@jitsusama/agentic-harness.core 0.1.0

package/dist/slack/resolvers/target.js

@@ -0,0 +1,45 @@
+/**
+ * Resolve a message target to a Conversation and timestamp.
+ *
+ * Many actions accept either a Slack permalink URL or a
+ * channel + timestamp pair. This module centralises that
+ * resolution so handlers don't repeat it.
+ */
+import { resolveConversation } from "./conversation.js";
+import { parseSlackUrl } from "./url.js";
+/**
+ * Resolve a message target from tool parameters.
+ *
+ * Accepts:
+ *   - target (Slack URL) → parsed, then conversation resolved
+ *   - channel + ts → conversation resolved
+ *
+ * Throws if neither provides enough information.
+ */
+export async function resolveTarget(client, target, channel, ts) {
+    // Slack permalink URL takes priority.
+    if (target) {
+        const parsed = parseSlackUrl(target);
+        if (parsed) {
+            const conversation = await resolveConversation(client, parsed.channel);
+            return { conversation, ts: parsed.ts };
+        }
+        // If it looks like a URL but didn't parse, try as a channel name.
+        if (!target.startsWith("http")) {
+            const conversation = await resolveConversation(client, target);
+            if (ts)
+                return { conversation, ts };
+        }
+        throw new Error("Could not parse the target URL. Provide a valid Slack permalink, " +
+            "or use the channel and ts parameters instead.");
+    }
+    // Channel + timestamp pair.
+    if (channel && ts) {
+        const conversation = await resolveConversation(client, channel);
+        return { conversation, ts };
+    }
+    if (channel && !ts) {
+        throw new Error("Missing timestamp (ts). Provide a message timestamp or use a Slack permalink URL as the target.");
+    }
+    throw new Error("Missing target. Provide a Slack permalink URL (target) or a channel + timestamp (ts) pair.");
+}

package/dist/slack/resolvers/url.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse Slack permalink URLs into channel ID and message timestamp.
+ *
+ * Accepts URLs like:
+ *   https://myteam.slack.com/archives/C0ACMKCS6UW/p1772132415861669
+ *   https://myteam.enterprise.slack.com/archives/C0ACMKCS6UW/p1772132415861669
+ */
+/** Parsed result from a Slack permalink URL. */
+export interface ParsedSlackUrl {
+    channel: string;
+    ts: string;
+}
+/**
+ * Extract channel ID and timestamp from a Slack message permalink.
+ *
+ * The timestamp in URLs has no dot: p1772132415861669 means
+ * 1772132415.861669 in the API. We insert the dot after the
+ * first 10 digits.
+ */
+export declare function parseSlackUrl(url: string): ParsedSlackUrl | null;

package/dist/slack/resolvers/url.js

@@ -0,0 +1,22 @@
+/**
+ * Parse Slack permalink URLs into channel ID and message timestamp.
+ *
+ * Accepts URLs like:
+ *   https://myteam.slack.com/archives/C0ACMKCS6UW/p1772132415861669
+ *   https://myteam.enterprise.slack.com/archives/C0ACMKCS6UW/p1772132415861669
+ */
+/**
+ * Extract channel ID and timestamp from a Slack message permalink.
+ *
+ * The timestamp in URLs has no dot: p1772132415861669 means
+ * 1772132415.861669 in the API. We insert the dot after the
+ * first 10 digits.
+ */
+export function parseSlackUrl(url) {
+    const match = url.match(/archives\/([A-Z0-9]+)\/p(\d+)/);
+    if (!match)
+        return null;
+    const rawTs = match[2];
+    const ts = `${rawTs.slice(0, 10)}.${rawTs.slice(10)}`;
+    return { channel: match[1], ts };
+}

package/dist/slack/resolvers/user.d.ts

@@ -0,0 +1,54 @@
+/**
+ * User handle → ID resolver.
+ *
+ * Accepts user handles (with or without @) and user IDs. Caches
+ * mappings at ~/.pi/agent/slack/users.json and resolves unknown
+ * handles via search.messages.
+ *
+ * On enterprise grids, users.list and users.lookupByEmail are
+ * often blocked, so we resolve handles by searching for a message
+ * from that user and extracting the user ID from the result.
+ *
+ * Often, not always: the email lookup is worth trying, because it
+ * is the only form that resolves somebody who has never posted a
+ * message the searcher can see. A blocked grid answers with an
+ * error, which degrades to the search rather than reaching the
+ * caller. A full name is refused outright, since `from:Chao Duan`
+ * cannot match and spending a call to learn that helps nobody.
+ */
+import type { SlackClient } from "../api/client.js";
+/**
+ * Resolve a user identifier to a user ID.
+ *
+ * Accepts:
+ *   - User ID (U... or W...) → returned as-is
+ *   - Username/handle (with or without @) → resolved via cache, then search
+ */
+export declare function resolveUser(client: SlackClient, input: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Look up a display name for any Slack entity ID.
+ *
+ * Routes by ID prefix:
+ *   - U/W → user cache (users.json)
+ *   - C/G → channel cache (channels.json)
+ *
+ * Returns the cached name if found, the raw ID otherwise.
+ * Local-only: no API calls.
+ */
+export declare function displayNameForId(id: string): string;
+/**
+ * Resolve a batch of user IDs to display names using the local cache.
+ * Returns a map of userId → displayName (handle if cached, raw ID if not).
+ * Local-only: no API calls.
+ */
+export declare function resolveUserIdsFromCache(userIds: string[]): Map<string, string>;
+/**
+ * Record a user handle → ID mapping.
+ * Called opportunistically when user data appears in API responses.
+ */
+export declare function cacheUser(name: string, id: string): void;
+/** List all cached user mappings. */
+export declare function listCachedUsers(): Array<{
+    name: string;
+    id: string;
+}>;

package/dist/slack/resolvers/user.js

@@ -0,0 +1,134 @@
+/**
+ * User handle → ID resolver.
+ *
+ * Accepts user handles (with or without @) and user IDs. Caches
+ * mappings at ~/.pi/agent/slack/users.json and resolves unknown
+ * handles via search.messages.
+ *
+ * On enterprise grids, users.list and users.lookupByEmail are
+ * often blocked, so we resolve handles by searching for a message
+ * from that user and extracting the user ID from the result.
+ *
+ * Often, not always: the email lookup is worth trying, because it
+ * is the only form that resolves somebody who has never posted a
+ * message the searcher can see. A blocked grid answers with an
+ * error, which degrades to the search rather than reaching the
+ * caller. A full name is refused outright, since `from:Chao Duan`
+ * cannot match and spending a call to learn that helps nobody.
+ */
+import { cacheMapping, listCached, lookupId, lookupName } from "./cache.js";
+const CACHE_FILE = "users.json";
+/** Pattern matching Slack user IDs (U or W prefix). */
+const USER_ID_PATTERN = /^[UW][A-Z0-9]{8,}$/;
+/**
+ * Resolve a user identifier to a user ID.
+ *
+ * Accepts:
+ *   - User ID (U... or W...) → returned as-is
+ *   - Username/handle (with or without @) → resolved via cache, then search
+ */
+export async function resolveUser(client, input, signal) {
+    if (USER_ID_PATTERN.test(input)) {
+        return input;
+    }
+    // Strip leading @.
+    const name = input.startsWith("@") ? input.slice(1) : input;
+    // Check cache first.
+    const cached = lookupId(CACHE_FILE, name);
+    if (cached)
+        return cached;
+    // A display name cannot be searched for: `from:` takes a handle, so
+    // `from:Chao Duan *` matches nothing and the failure arrives after a
+    // round trip, phrased as though the name were misspelled.
+    if (/\s/.test(name)) {
+        throw new Error(`Could not resolve user "${input}": a full name cannot be looked up. ` +
+            "Use their email address, their Slack handle (as in @joel.gerber) " +
+            "or a user ID (as in U0123ABC).");
+    }
+    // An email is the one form that resolves somebody who has posted
+    // nothing visible. Blocked on some grids, which is not the caller's
+    // problem: fall through to the search.
+    if (name.includes("@")) {
+        const byEmail = await lookUpByEmail(client, name, signal);
+        if (byEmail)
+            return byEmail;
+    }
+    // Resolve via search. Enterprise grids block users.list,
+    // but search.messages with from:username works.
+    const response = await client.call("search.messages", { query: `from:${name} *`, count: 1 }, signal);
+    const match = response.messages?.matches?.[0];
+    if (match?.user && match?.username) {
+        cacheUser(match.username, match.user);
+        return match.user;
+    }
+    throw new Error(`Could not resolve user "${input}". ` +
+        "Use their email address, a user ID (e.g. U0123ABC), or verify the handle.");
+}
+/**
+ * The user behind an email address, or undefined when this grid will not
+ * say.
+ *
+ * A refusal here is expected rather than exceptional: the method is
+ * commonly restricted, and a caller who passed an email should get the
+ * search's answer instead of the grid's policy.
+ */
+async function lookUpByEmail(client, email, signal) {
+    try {
+        const response = await client.call("users.lookupByEmail", { email }, signal);
+        const id = response.user?.id;
+        if (!id)
+            return undefined;
+        if (response.user?.name)
+            cacheUser(response.user.name, id);
+        cacheUser(email, id);
+        return id;
+    }
+    catch {
+        // Blocked, or no such address. Either way the search may still
+        // answer, and the refusal at the end of the caller says both forms.
+        return undefined;
+    }
+}
+/** Cache file for channel name ↔ ID mappings. */
+const CHANNEL_CACHE_FILE = "channels.json";
+/**
+ * Look up a display name for any Slack entity ID.
+ *
+ * Routes by ID prefix:
+ *   - U/W → user cache (users.json)
+ *   - C/G → channel cache (channels.json)
+ *
+ * Returns the cached name if found, the raw ID otherwise.
+ * Local-only: no API calls.
+ */
+export function displayNameForId(id) {
+    if (id.startsWith("C") || id.startsWith("G")) {
+        return lookupName(CHANNEL_CACHE_FILE, id) ?? id;
+    }
+    return lookupName(CACHE_FILE, id) ?? id;
+}
+/**
+ * Resolve a batch of user IDs to display names using the local cache.
+ * Returns a map of userId → displayName (handle if cached, raw ID if not).
+ * Local-only: no API calls.
+ */
+export function resolveUserIdsFromCache(userIds) {
+    const result = new Map();
+    for (const id of userIds) {
+        result.set(id, lookupName(CACHE_FILE, id) ?? id);
+    }
+    return result;
+}
+/**
+ * Record a user handle → ID mapping.
+ * Called opportunistically when user data appears in API responses.
+ */
+export function cacheUser(name, id) {
+    if (name && id) {
+        cacheMapping(CACHE_FILE, name, id);
+    }
+}
+/** List all cached user mappings. */
+export function listCachedUsers() {
+    return listCached(CACHE_FILE);
+}

package/dist/slack/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Shared types for the Slack integration extension.
+ */
+/** OAuth app credentials (client ID + secret). */
+export interface OAuthApp {
+    readonly clientId: string;
+    readonly clientSecret: string;
+}
+/**
+ * Stored Slack credentials.
+ *
+ * Supports two auth modes:
+ *   - OAuth user tokens (xoxp-): proper OAuth2 flow, no cookie needed
+ *   - Browser session tokens (xoxc-): extracted from browser, requires cookie
+ *
+ * Enterprise workspaces often block app creation, making browser
+ * session tokens the only viable option.
+ */
+export interface StoredToken {
+    accessToken: string;
+    cookie?: string;
+    userId: string;
+    teamId: string;
+    teamName?: string;
+    scopes: string;
+}
+/** Parameters passed to router actions. */
+export type ActionParams = Record<string, unknown>;
+/** Extract a string parameter, returning undefined if absent or wrong type. */
+export declare function stringParam(params: ActionParams, key: string): string | undefined;
+/** Extract a number parameter, returning undefined if absent or wrong type. */
+export declare function numberParam(params: ActionParams, key: string): number | undefined;
+/** Content block in a tool result: text or base64 image. */
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/** Result of a tool execution. */
+export interface ToolResult {
+    content: ToolContent[];
+    details?: unknown;
+}
+/** Classification of a Slack conversation. */
+export type ConversationKind = "channel" | "dm" | "group_dm";
+/**
+ * A Slack conversation at any level of resolution.
+ *
+ * Created during input resolution (router) and enriched
+ * during output formatting (post-fetch message rendering).
+ * Fields that aren't available yet are undefined.
+ */
+export interface Conversation {
+    /** Slack conversation ID (C..., D..., G...). Always present. */
+    id: string;
+    /** Raw Slack channel name (e.g. "gitstream"). Undefined for DMs. */
+    name?: string;
+    /** What kind of conversation this is. */
+    kind: ConversationKind;
+    /** Human-readable name: "#gitstream", "@chao.duan", "@a, @b, @c". */
+    displayName?: string;
+    /** The other person's user ID. Only set when kind is "dm". */
+    dmUserId?: string;
+}
+/**
+ * A message target: a conversation plus a timestamp.
+ *
+ * For thread replies, `threadTs` identifies the parent
+ * message. When absent, the message is assumed to be
+ * a top-level channel message.
+ */
+export interface MessageTarget {
+    conversation: Conversation;
+    ts: string;
+    threadTs?: string;
+}
+/** Resolved identifiers from tool parameters. */
+export interface ResolvedParams {
+    /** Resolved conversation (from `channel` param, `target`, or `channel` + `ts`). */
+    conversation?: Conversation;
+    /** Resolved message target (from `target` param or `channel` + `ts`). */
+    target?: MessageTarget;
+    /** Resolved user ID (from `user` param). */
+    userId?: string;
+}
+/** An attachment or link unfurl on a Slack message. */
+export interface SlackAttachment {
+    title?: string;
+    text?: string;
+    fallback?: string;
+    fromUrl?: string;
+    imageUrl?: string;
+}
+/** A file attached to a Slack message. */
+export interface SlackFile {
+    name: string;
+    mimetype?: string;
+    url?: string;
+}
+/** Per-column display settings for a Slack table block. */
+export interface SlackColumnSetting {
+    /** Text alignment: "left" (default), "center", or "right". */
+    align?: "left" | "center" | "right";
+    /** Whether text wraps instead of truncating. */
+    isWrapped?: boolean;
+}
+/**
+ * A table extracted from or destined for a Slack table block.
+ *
+ * When reading, columns and rows contain rendered text
+ * (rich text elements converted to readable strings).
+ * When sending, they contain mrkdwn strings that get
+ * converted to Block Kit elements.
+ */
+export interface SlackTable {
+    /** Header row labels. */
+    columns: string[];
+    /** Data rows. Each row has the same length as columns. */
+    rows: string[][];
+    /** Per-column settings (positional). Use null to skip a column. */
+    columnSettings?: (SlackColumnSetting | null)[];
+}
+/** A Slack message as returned by the API. */
+export interface SlackMessage {
+    ts: string;
+    text: string;
+    user?: string;
+    /** The conversation this message belongs to. */
+    conversation?: Conversation;
+    threadTs?: string;
+    replyCount?: number;
+    /** True when this message started a thread (threadTs === ts). */
+    isThreadParent?: boolean;
+    reactions?: SlackReaction[];
+    attachments?: SlackAttachment[];
+    files?: SlackFile[];
+    /** Tables extracted from Block Kit table blocks. */
+    tables?: SlackTable[];
+    permalink?: string;
+}
+/** A reaction on a Slack message. */
+export interface SlackReaction {
+    name: string;
+    count: number;
+    users: string[];
+}
+/** Channel metadata. */
+export interface SlackChannel {
+    id: string;
+    name: string;
+    topic?: string;
+    purpose?: string;
+    memberCount?: number;
+    isArchived: boolean;
+    isPrivate: boolean;
+    created?: number;
+}
+/** User profile. */
+export interface SlackUser {
+    id: string;
+    name: string;
+    realName?: string;
+    displayName?: string;
+    title?: string;
+    email?: string;
+    isBot: boolean;
+    isAdmin: boolean;
+    timezone?: string;
+    statusText?: string;
+    statusEmoji?: string;
+    deleted: boolean;
+}
+/** Search result metadata. */
+export interface SearchResult {
+    messages: SlackMessage[];
+    total: number;
+}

package/dist/slack/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared types for the Slack integration extension.
+ */
+/** Extract a string parameter, returning undefined if absent or wrong type. */
+export function stringParam(params, key) {
+    const value = params[key];
+    return typeof value === "string" ? value : undefined;
+}
+/** Extract a number parameter, returning undefined if absent or wrong type. */
+export function numberParam(params, key) {
+    const value = params[key];
+    return typeof value === "number" ? value : undefined;
+}

package/dist/tdd/attest.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one command this domain exposes: attest a transition
+ * against the current loop. Pure, synchronous, no I/O — a
+ * discriminated result the caller pattern-matches on. Persisting
+ * the returned loop between calls, and deciding how its own host
+ * surfaces `discipline`/`guidance`, is entirely the adapter's job.
+ */
+import type { Attestation, Loop } from "./machine.js";
+export type { Attestation, Loop };
+/** The outcome of attesting one transition: advanced, or refused unchanged. */
+export type AttestResult = {
+    outcome: "advanced";
+    loop: Loop;
+    discipline: string;
+} | {
+    outcome: "refused";
+    loop: Loop;
+    guidance: string;
+};
+/** Attempt a transition, enforcing the justification each gate requires. */
+export declare function attest(loop: Loop, attestation: Attestation): AttestResult;

package/dist/tdd/attest.js

@@ -0,0 +1,21 @@
+/**
+ * The one command this domain exposes: attest a transition
+ * against the current loop. Pure, synchronous, no I/O — a
+ * discriminated result the caller pattern-matches on. Persisting
+ * the returned loop between calls, and deciding how its own host
+ * surfaces `discipline`/`guidance`, is entirely the adapter's job.
+ */
+import { disciplineFor } from "./discipline.js";
+import { transition } from "./machine.js";
+/** Attempt a transition, enforcing the justification each gate requires. */
+export function attest(loop, attestation) {
+    const result = transition(loop, attestation);
+    if (!result.ok) {
+        return { outcome: "refused", loop, guidance: result.guidance };
+    }
+    return {
+        outcome: "advanced",
+        loop: result.loop,
+        discipline: disciplineFor(result.loop.phase),
+    };
+}

package/dist/tdd/discipline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The standing discipline for each phase: the one or two
+ * sentences the agent should keep in mind while it's there. An
+ * adapter injects these as a reminder, both in the reply when a
+ * transition lands and in whatever persistent context mechanism
+ * its host offers, so the discipline survives a long autonomous
+ * run.
+ */
+import type { Phase } from "./machine.js";
+/** The standing discipline to keep in mind during a phase. */
+export declare function disciplineFor(phase: Phase): string;

package/dist/tdd/discipline.js

@@ -0,0 +1,28 @@
+/**
+ * The standing discipline for each phase: the one or two
+ * sentences the agent should keep in mind while it's there. An
+ * adapter injects these as a reminder, both in the reply when a
+ * transition lands and in whatever persistent context mechanism
+ * its host offers, so the discipline survives a long autonomous
+ * run.
+ */
+const DISCIPLINE = {
+    idle: "No loop is active. Start one when you're ready for the next single " +
+        "increment.",
+    plan: "One increment. Describe the intent: the behaviour you want, not the " +
+        "code that already exists.",
+    write: "Bind the test to the exported surface only. Internals are never tested " +
+        "directly. If the test is hard to write, the design is wrong, so " +
+        "redesign the interface before you go on.",
+    red: "The failure has to be a real assertion, not a missing symbol or a " +
+        "compile error. For a wrong red, stub a minimal skeleton and nothing " +
+        "more.",
+    green: "Write the minimum code to pass. No fictional futures. Do not touch the " +
+        "test to make it green.",
+    refactor: "Behaviour preserved, tests stay green. Step back and reconsider the " +
+        "internal and external design now that a real consumer need exists.",
+};
+/** The standing discipline to keep in mind during a phase. */
+export function disciplineFor(phase) {
+    return DISCIPLINE[phase];
+}

package/dist/tdd/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public API for the `tdd` domain: drive a single, discrete
+ * red-green-refactor loop by attesting each transition.
+ *
+ * Deliberately not exported here: persistence (each adapter's
+ * job — pi via its session log, a CLI via a small state file it
+ * owns) and rendering (`./presentation`, for hosts with a
+ * scoreboard).
+ */
+export { type AttestResult, attest } from "./attest.js";
+export { disciplineFor } from "./discipline.js";
+export type { Action, Attestation, FailureKind, Loop, Phase, } from "./machine.js";
+export { idleLoop } from "./machine.js";
+export { standingReminder } from "./queries.js";

package/dist/tdd/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public API for the `tdd` domain: drive a single, discrete
+ * red-green-refactor loop by attesting each transition.
+ *
+ * Deliberately not exported here: persistence (each adapter's
+ * job — pi via its session log, a CLI via a small state file it
+ * owns) and rendering (`./presentation`, for hosts with a
+ * scoreboard).
+ */
+export { attest } from "./attest.js";
+export { disciplineFor } from "./discipline.js";
+export { idleLoop } from "./machine.js";
+export { standingReminder } from "./queries.js";

package/dist/tdd/machine.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The TDD loop domain model and its pure reducer: a single,
+ * discrete red-green-refactor loop.
+ *
+ * The agent drives the loop by attesting each transition. A
+ * transition is allowed only when the attestation supplies the
+ * justification the gate requires; otherwise the reducer refuses
+ * and hands back guidance. The reducer never inspects code, test
+ * output or file paths. It tracks the agent's own attestation,
+ * which is the one contract that stays robust across every
+ * language and every host this loop ever runs under.
+ */
+/** Where a loop sits in the red-green-refactor cycle. */
+export type Phase = "idle" | "plan" | "write" | "red" | "green" | "refactor";
+/** Whether a reported failure is a real assertion or noise. */
+export type FailureKind = "assertion" | "other";
+/** The live state of one discrete TDD loop. */
+export interface Loop {
+    phase: Phase;
+    assertionFailure: boolean;
+    behaviour: string | null;
+    iteration: number;
+}
+/** The resting state: no loop in play. */
+export declare function idleLoop(): Loop;
+/** The transitions the agent can attest. */
+export type Action = "plan" | "write" | "red" | "green" | "refactor" | "done" | "abandon";
+/** A transition request, carrying whatever justification it offers. */
+export interface Attestation {
+    action: Action;
+    behaviour?: string;
+    interface?: string;
+    failure?: string;
+    failureKind?: FailureKind;
+    pass?: string;
+    reflection?: string;
+    reason?: string;
+}
+/** The reducer's own outcome: advance, or refuse with guidance. */
+export type TransitionResult = {
+    ok: true;
+    loop: Loop;
+} | {
+    ok: false;
+    guidance: string;
+};
+/** Attempt a transition, enforcing the justification each gate requires. */
+export declare function transition(loop: Loop, attestation: Attestation): TransitionResult;