@clawmem-ai/clawmem 0.1.18 → 0.1.19

package/dist/src/conversation.js

@@ -0,0 +1,323 @@
+// Session mirroring: creates/updates GitHub issues and comments for each conversation.
+import fs from "node:fs";
+import path from "node:path";
+import { AGENT_LABEL_PREFIX, DEFAULT_LABELS, SESSION_TITLE_PREFIX, extractLabelNames } from "./config.js";
+import { parseCandidates } from "./memory.js";
+import { normalizeMessages, readTranscriptSnapshot } from "./transcript.js";
+import { fmtTranscript, localDate, localDateTime, sha256, subKey } from "./utils.js";
+import { stringifyFlatYaml } from "./yaml.js";
+const FINALIZE_SCHEMA_KIND_LIMIT = 24;
+const FINALIZE_SCHEMA_TOPIC_LIMIT = 80;
+export class ConversationMirror {
+    client;
+    api;
+    config;
+    constructor(client, api, config) {
+        this.client = client;
+        this.api = api;
+        this.config = config;
+    }
+    shouldMirror(sessionId, messages) {
+        if (sessionId.startsWith("slug-generator-"))
+            return false;
+        const first = messages.find((m) => m.role === "user")?.text ?? "";
+        if (first.includes("generate a short 1-2 word filename slug") && first.includes("Reply with ONLY the slug"))
+            return false;
+        if (first.includes("Write the final issue summary and extract durable memory candidates from the conversation below."))
+            return false;
+        return true;
+    }
+    async loadSnapshot(session, fallback) {
+        const normalizedFallback = normalizeMessages(fallback);
+        if (normalizedFallback.length > 0) {
+            return { sessionId: session.sessionId, messages: normalizedFallback };
+        }
+        const filePath = await this.resolveTranscriptPath(session.sessionFile);
+        if (filePath) {
+            session.sessionFile = filePath;
+            try {
+                const t = await readTranscriptSnapshot(filePath);
+                return { sessionId: t.sessionId ?? session.sessionId, messages: t.messages };
+            }
+            catch (error) {
+                this.api.logger.warn(`clawmem: transcript read failed for ${filePath}: ${String(error)}`);
+            }
+        }
+        return { sessionId: session.sessionId, messages: normalizedFallback };
+    }
+    async ensureIssue(session, snapshot) {
+        if (session.issueNumber) {
+            const existing = await this.lookupBoundIssue(session);
+            if (existing && this.isBoundIssue(session, existing)) {
+                session.issueTitle = existing.title?.trim() || session.issueTitle;
+                return;
+            }
+            this.api.logger.warn(`clawmem: issue binding for ${session.sessionId} is stale or mismatched (${session.issueNumber}); recreating`);
+            this.resetIssueBinding(session);
+        }
+        // Use placeholder title; real title is generated by LLM once enough messages are available.
+        const title = deriveInitialTitle(snapshot.messages, session.sessionId);
+        const labels = this.buildLabels(session, snapshot, false);
+        const body = this.renderBody(session, snapshot, "pending", false);
+        await this.client.ensureLabels(labels);
+        const issue = await this.client.createIssue({ title, body, labels });
+        session.issueNumber = issue.number;
+        session.issueTitle = issue.title ?? title;
+        session.titleSource = "placeholder";
+        session.lastSummaryHash = sha256(`${title}\n${body}\nopen`);
+        session.createdAt = new Date().toISOString();
+        session.updatedAt = session.createdAt;
+    }
+    async syncBody(session, snapshot, summary, closed, titleOverride) {
+        if (!session.issueNumber)
+            return;
+        // Prefer explicit override (LLM-generated title), then keep existing title, then fall back to session ID.
+        const title = titleOverride?.trim() || session.issueTitle || `${SESSION_TITLE_PREFIX}${session.sessionId}`;
+        const body = this.renderBody(session, snapshot, summary, closed);
+        const hash = sha256(`${title}\n${body}\n${closed ? "closed" : "open"}`);
+        if (hash === session.lastSummaryHash)
+            return;
+        await this.client.updateIssue(session.issueNumber, { title, body, ...(closed ? { state: "closed" } : {}) });
+        session.issueTitle = title;
+        if (titleOverride?.trim())
+            session.titleSource = "llm";
+        session.lastSummaryHash = hash;
+    }
+    async syncLabels(session, snapshot, closed) {
+        if (!session.issueNumber)
+            return;
+        const labels = this.buildLabels(session, snapshot, closed);
+        await this.client.ensureLabels(labels);
+        await this.client.syncManagedLabels(session.issueNumber, labels);
+    }
+    async appendComments(issueNumber, messages) {
+        let count = 0;
+        for (const msg of messages) {
+            try {
+                await this.client.createComment(issueNumber, `role: ${msg.role}\n\n${msg.text.trim()}`);
+                count++;
+            }
+            catch (error) {
+                this.api.logger.warn(`clawmem: conversation comment failed: ${String(error)}`);
+                break;
+            }
+        }
+        return count;
+    }
+    async generateFinalArtifacts(session, snapshot, schema) {
+        if (snapshot.messages.length === 0)
+            throw new Error("no conversation messages to finalize");
+        const subagent = this.api.runtime.subagent;
+        const sessionKey = subKey(session, "finalize");
+        const message = buildFinalizeArtifactsPrompt(snapshot, schema);
+        try {
+            const run = await subagent.run({
+                sessionKey,
+                message,
+                deliver: false,
+                lane: "clawmem-finalize",
+                idempotencyKey: sha256(`${session.sessionId}:${snapshot.messages.length}:finalize-v2`),
+                extraSystemPrompt: "You finalize ClawMem conversations. Output JSON only with summary, title, and durable memory candidates. Reuse existing schema when it fits and keep human-readable memory text in the conversation language.",
+            });
+            const wait = await subagent.waitForRun({
+                runId: run.runId,
+                timeoutMs: Math.max(this.config.summaryWaitTimeoutMs, this.config.memoryExtractWaitTimeoutMs),
+            });
+            if (wait.status === "timeout")
+                throw new Error("finalize subagent timed out");
+            if (wait.status === "error")
+                throw new Error(wait.error || "finalize subagent failed");
+            const msgs = normalizeMessages((await subagent.getSessionMessages({ sessionKey, limit: 50 })).messages);
+            const text = [...msgs].reverse().find((entry) => entry.role === "assistant" && entry.text.trim())?.text;
+            if (!text)
+                throw new Error("finalize subagent returned no assistant text");
+            return parseFinalArtifacts(text);
+        }
+        finally {
+            subagent.deleteSession({ sessionKey, deleteTranscript: true }).catch(() => { });
+        }
+    }
+    buildLabels(session, _snapshot, _closed) {
+        const labels = new Set([...DEFAULT_LABELS, "type:conversation", `session:${session.sessionId}`]);
+        if (session.agentId)
+            labels.add(`${AGENT_LABEL_PREFIX}${session.agentId}`);
+        return [...labels].filter((l) => l.trim().length > 0);
+    }
+    renderBody(session, snapshot, summary, _closed) {
+        const dates = this.resolveDates(session, snapshot.messages);
+        return stringifyFlatYaml([
+            ["type", "conversation"], ["session_id", session.sessionId], ["date", dates.date],
+            ["start_at", dates.startAt], ["end_at", dates.endAt],
+            ["summary", summary],
+        ]);
+    }
+    resolveDates(session, messages) {
+        const ts = messages.map((m) => m.timestamp).filter((v) => Boolean(v?.trim()))
+            .map((v) => new Date(v)).filter((d) => Number.isFinite(d.getTime()));
+        const fallbackStart = session.createdAt ? new Date(session.createdAt) : new Date();
+        const fallbackEnd = session.updatedAt ? new Date(session.updatedAt) : fallbackStart;
+        const start = ts[0] ?? fallbackStart, end = ts.at(-1) ?? fallbackEnd;
+        return { date: localDate(start), startAt: localDateTime(start), endAt: localDateTime(end) };
+    }
+    async resolveTranscriptPath(filePath) {
+        if (!filePath)
+            return null;
+        if (await fexists(filePath))
+            return filePath;
+        try {
+            const dir = path.dirname(filePath), prefix = `${path.basename(filePath)}.reset.`;
+            const latest = (await fs.promises.readdir(dir, { withFileTypes: true }))
+                .filter((e) => e.isFile() && e.name.startsWith(prefix)).map((e) => e.name).sort().at(-1);
+            if (latest) {
+                this.api.logger.info?.(`clawmem: using reset transcript ${path.join(dir, latest)} because ${filePath} is missing`);
+                return path.join(dir, latest);
+            }
+        }
+        catch { /* directory unreadable */ }
+        return null;
+    }
+    async lookupBoundIssue(session) {
+        if (!session.issueNumber)
+            return null;
+        try {
+            return await this.client.getIssue(session.issueNumber);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        }
+    }
+    isBoundIssue(session, issue) {
+        const labels = extractLabelNames(issue.labels);
+        return labels.includes("type:conversation") && labels.includes(`session:${session.sessionId}`);
+    }
+    resetIssueBinding(session) {
+        session.issueNumber = undefined;
+        session.issueTitle = undefined;
+        session.titleSource = undefined;
+        session.lastSummaryHash = undefined;
+        session.lastMirroredCount = 0;
+        session.turnCount = 0;
+        session.finalizedAt = undefined;
+    }
+}
+export function buildFinalizeArtifactsPrompt(snapshot, schema) {
+    return [
+        "Write the final issue summary and extract durable memory candidates from the conversation below.",
+        'Return valid JSON only in the form {"summary":"...","title":"...","candidates":[{"title":"...","detail":"...","kind":"...","topics":["..."],"evidence":"..."}]}.',
+        "The summary should be concise, factual, and written in 2-4 sentences.",
+        "Do not include markdown, bullet points, or analysis.",
+        "",
+        "Title rules:",
+        "- Under 50 characters, accurately describe the main topic or task.",
+        "- Should let someone immediately know what the conversation is about.",
+        "- Must be in the same language as the majority of the conversation content.",
+        "- Good: precise, descriptive, specific. Bad: vague, overly creative, generic.",
+        "",
+        "Candidate rules:",
+        "- Extract only durable facts, preferences, decisions, constraints, workflows, and ongoing context worth remembering later.",
+        "- Each candidate must represent one durable fact. Split independent facts into separate candidates.",
+        "- Prefer a concise explicit title for each candidate whenever the fact can be named clearly.",
+        "- Candidate titles and details must be in the same language as the majority of the conversation content.",
+        "- Do not extract temporary requests, tool chatter, startup boilerplate, or summaries about internal helper sessions.",
+        "- Reuse existing schema labels when one already fits.",
+        "- If no existing kind or topic fits, create one short stable machine-readable label instead of a translated or near-duplicate variant.",
+        "- Keep kind and topic labels short, reusable, low-cardinality, and machine-readable.",
+        "- Evidence is optional. If present, keep it short and quote-free.",
+        "- Prefer an empty candidates array when nothing durable was learned.",
+        "",
+        ...buildFinalizeSchemaSection(schema),
+        "<conversation>",
+        fmtTranscript(snapshot.messages),
+        "</conversation>",
+    ].join("\n");
+}
+function buildFinalizeSchemaSection(schema) {
+    if (!schema)
+        return [];
+    const kinds = schema.kinds.map((kind) => kind.trim()).filter(Boolean);
+    const topics = schema.topics.map((topic) => topic.trim()).filter(Boolean);
+    if (kinds.length === 0 && topics.length === 0)
+        return [];
+    const kindLines = kinds.slice(0, FINALIZE_SCHEMA_KIND_LIMIT).map((kind) => `- kind:${kind}`);
+    const topicLines = topics.slice(0, FINALIZE_SCHEMA_TOPIC_LIMIT).map((topic) => `- topic:${topic}`);
+    const kindOverflow = kinds.length > kindLines.length ? [`- ...and ${kinds.length - kindLines.length} more kinds`] : [];
+    const topicOverflow = topics.length > topicLines.length ? [`- ...and ${topics.length - topicLines.length} more topics`] : [];
+    return [
+        "Current schema to reuse first:",
+        "<current-schema>",
+        "Kinds:",
+        ...(kindLines.length > 0 ? kindLines : ["- None"]),
+        ...kindOverflow,
+        "Topics:",
+        ...(topicLines.length > 0 ? topicLines : ["- None"]),
+        ...topicOverflow,
+        "</current-schema>",
+        "Prefer these existing labels whenever they fit. Only create a new label when none of the current labels matches the fact you are storing.",
+        "",
+    ];
+}
+async function fexists(p) { try {
+    return (await fs.promises.stat(p)).isFile();
+}
+catch {
+    return false;
+} }
+function isNotFoundError(error) {
+    const text = String(error);
+    return text.includes("HTTP 404");
+}
+/** Derive an initial placeholder title for a new conversation. The real title is generated by LLM once enough messages are available. */
+export function deriveInitialTitle(_messages, sessionId) {
+    return `${SESSION_TITLE_PREFIX}${sessionId}`;
+}
+function parseSummaryAndTitle(raw) {
+    const tryParse = (s) => {
+        try {
+            const p = JSON.parse(s);
+            const summary = typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null;
+            if (!summary)
+                return null;
+            const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+            return { summary, title };
+        }
+        catch {
+            const i = s.indexOf("{"), j = s.lastIndexOf("}");
+            if (i >= 0 && j > i) {
+                try {
+                    const p = JSON.parse(s.slice(i, j + 1));
+                    const summary = typeof p?.summary === "string" && p.summary.trim() ? p.summary.trim() : null;
+                    if (!summary)
+                        return null;
+                    const title = typeof p?.title === "string" && p.title.trim() ? p.title.trim() : undefined;
+                    return { summary, title };
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        }
+    };
+    const t = raw.trim();
+    const direct = tryParse(t);
+    if (direct)
+        return direct;
+    const f = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+    if (f?.[1]) {
+        const nested = tryParse(f[1].trim());
+        if (nested)
+            return nested;
+    }
+    return { summary: t };
+}
+function parseFinalArtifacts(raw) {
+    const parsedSummary = parseSummaryAndTitle(raw);
+    const candidates = parseCandidates(raw);
+    return {
+        summary: parsedSummary.summary,
+        ...(parsedSummary.title ? { title: parsedSummary.title } : {}),
+        candidates,
+    };
+}

package/dist/src/github-client.d.ts

@@ -0,0 +1,269 @@
+import type { AgentRegistrationResponse, AnonymousSessionResponse, ClawMemResolvedRoute } from "./types.js";
+export type IssueResponse = {
+    id?: number;
+    number: number;
+    title?: string;
+    body?: string;
+    state?: string;
+    state_reason?: string | null;
+    locked?: boolean;
+    labels?: Array<{
+        name?: string;
+    } | string>;
+    assignees?: Array<{
+        login?: string;
+        name?: string;
+    }>;
+    user?: {
+        login?: string;
+        name?: string;
+    };
+    comments?: number;
+    created_at?: string;
+    updated_at?: string;
+    closed_at?: string | null;
+    html_url?: string;
+    url?: string;
+};
+export type CommentResponse = {
+    id?: number;
+    body?: string;
+    created_at?: string;
+    updated_at?: string;
+    html_url?: string;
+    url?: string;
+    in_reply_to_id?: number | null;
+    user?: {
+        login?: string;
+        name?: string;
+    };
+};
+type LabelResponse = {
+    name?: string;
+    color?: string;
+    description?: string;
+};
+type PermissionMap = Record<string, boolean | undefined>;
+export type RepoResponse = {
+    name?: string;
+    full_name?: string;
+    description?: string;
+    private?: boolean;
+    owner?: {
+        login?: string;
+    };
+    permissions?: PermissionMap;
+    role_name?: string;
+};
+type OrgResponse = {
+    id?: number;
+    login?: string;
+    name?: string;
+    description?: string;
+    default_repository_permission?: string;
+};
+type TeamResponse = {
+    id?: number;
+    slug?: string;
+    name?: string;
+    description?: string;
+    privacy?: string;
+    permission?: string;
+    role_name?: string;
+    permissions?: PermissionMap;
+};
+type CollaboratorResponse = {
+    id?: number;
+    login?: string;
+    name?: string;
+    permissions?: PermissionMap;
+    role_name?: string;
+    organization_member?: boolean;
+    outside_collaborator?: boolean;
+    type?: string;
+};
+type CurrentUserResponse = {
+    id?: number;
+    login?: string;
+    name?: string;
+};
+type RepositoryInvitationResponse = {
+    id?: number;
+    created_at?: string;
+    permissions?: string;
+    repository?: RepoResponse;
+    invitee?: {
+        login?: string;
+        name?: string;
+    };
+    inviter?: {
+        login?: string;
+        name?: string;
+    };
+};
+type TeamMembershipResponse = {
+    state?: string;
+    role?: string;
+};
+type OrganizationMembershipResponse = {
+    state?: string;
+    role?: string;
+    organization?: OrgResponse;
+    user?: CollaboratorResponse;
+};
+type InvitationResponse = {
+    id?: number;
+    role?: string;
+    created_at?: string;
+    expires_at?: string | null;
+    email?: string;
+    login?: string;
+    organization?: OrgResponse;
+    invitee?: {
+        login?: string;
+    };
+    inviter?: {
+        login?: string;
+    };
+    team_ids?: number[];
+    teams?: TeamResponse[];
+};
+export declare class GitHubIssueClient {
+    private readonly config;
+    private readonly log;
+    constructor(config: ClawMemResolvedRoute, log: {
+        warn?: (msg: string) => void;
+    });
+    repo(): string | undefined;
+    defaultRepo(): string | undefined;
+    createIssue(params: {
+        title: string;
+        body?: string;
+        labels?: string[];
+        assignees?: string[];
+        assignee?: string;
+        state?: "open" | "closed";
+        stateReason?: string;
+    }): Promise<IssueResponse>;
+    updateIssue(n: number, params: {
+        title?: string;
+        body?: string;
+        state?: "open" | "closed";
+        stateReason?: string;
+        labels?: string[];
+        assignees?: string[];
+        locked?: boolean;
+    }): Promise<IssueResponse>;
+    getIssue(n: number): Promise<IssueResponse>;
+    createComment(issueNumber: number, body: string, params?: {
+        inReplyTo?: number;
+    }): Promise<CommentResponse>;
+    listComments(issueNumber: number, params?: {
+        page?: number;
+        perPage?: number;
+        sort?: "created" | "updated";
+        direction?: "asc" | "desc";
+        since?: string;
+        threaded?: boolean;
+    }): Promise<CommentResponse[]>;
+    listIssues(params: {
+        labels?: string[];
+        state?: "open" | "closed" | "all";
+        assignee?: string;
+        creator?: string;
+        mentioned?: string;
+        sort?: "created" | "updated" | "comments";
+        direction?: "asc" | "desc";
+        since?: string;
+        page?: number;
+        perPage?: number;
+    }): Promise<IssueResponse[]>;
+    searchIssues(query: string, params?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<IssueResponse[]>;
+    listLabels(params?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<LabelResponse[]>;
+    listUserRepos(): Promise<RepoResponse[]>;
+    createUserRepo(params: {
+        name: string;
+        description?: string;
+        private?: boolean;
+        autoInit?: boolean;
+    }): Promise<RepoResponse>;
+    createOrgRepo(org: string, params: {
+        name: string;
+        description?: string;
+        private?: boolean;
+        autoInit?: boolean;
+        hasIssues?: boolean;
+        hasWiki?: boolean;
+    }): Promise<RepoResponse>;
+    listUserOrgs(): Promise<OrgResponse[]>;
+    getCurrentUser(): Promise<CurrentUserResponse>;
+    createUserOrg(params: {
+        login: string;
+        name?: string;
+        defaultRepositoryPermission?: string;
+    }): Promise<OrgResponse>;
+    getOrg(org: string): Promise<OrgResponse>;
+    listOrgMembers(org: string, role?: "admin"): Promise<CollaboratorResponse[]>;
+    getOrgMembership(org: string, username: string): Promise<OrganizationMembershipResponse>;
+    removeOrgMember(org: string, username: string): Promise<void>;
+    removeOrgMembership(org: string, username: string): Promise<void>;
+    listOrgTeams(org: string): Promise<TeamResponse[]>;
+    getTeam(org: string, teamSlug: string): Promise<TeamResponse>;
+    createOrgTeam(org: string, params: {
+        name: string;
+        description?: string;
+        privacy?: "closed" | "secret";
+    }): Promise<TeamResponse>;
+    updateTeam(org: string, teamSlug: string, params: {
+        name?: string;
+        description?: string;
+        privacy?: "closed" | "secret";
+    }): Promise<TeamResponse>;
+    deleteTeam(org: string, teamSlug: string): Promise<void>;
+    listTeamMembers(org: string, teamSlug: string): Promise<CollaboratorResponse[]>;
+    setTeamMembership(org: string, teamSlug: string, username: string, role: "member" | "maintainer"): Promise<TeamMembershipResponse>;
+    removeTeamMembership(org: string, teamSlug: string, username: string): Promise<void>;
+    listTeamRepos(org: string, teamSlug: string): Promise<RepoResponse[]>;
+    setTeamRepoAccess(org: string, teamSlug: string, owner: string, repo: string, permission: "read" | "write" | "admin"): Promise<void>;
+    removeTeamRepoAccess(org: string, teamSlug: string, owner: string, repo: string): Promise<void>;
+    listRepoCollaborators(owner: string, repo: string): Promise<CollaboratorResponse[]>;
+    listRepoInvitations(owner: string, repo: string): Promise<RepositoryInvitationResponse[]>;
+    setRepoCollaborator(owner: string, repo: string, username: string, permission: "read" | "write" | "admin"): Promise<RepositoryInvitationResponse | undefined>;
+    removeRepoCollaborator(owner: string, repo: string, username: string): Promise<void>;
+    getRepo(owner: string, repo: string): Promise<RepoResponse>;
+    listUserRepoInvitations(): Promise<RepositoryInvitationResponse[]>;
+    acceptUserRepoInvitation(invitationId: number): Promise<void>;
+    declineUserRepoInvitation(invitationId: number): Promise<void>;
+    listOrgInvitations(org: string): Promise<InvitationResponse[]>;
+    createOrgInvitation(org: string, params: {
+        inviteeLogin: string;
+        role?: "member" | "owner";
+        teamIds?: number[];
+        expiresInDays?: number;
+    }): Promise<InvitationResponse>;
+    revokeOrgInvitation(org: string, invitationId: number): Promise<void>;
+    listOrgOutsideCollaborators(org: string): Promise<CollaboratorResponse[]>;
+    listUserOrgInvitations(): Promise<InvitationResponse[]>;
+    acceptUserOrgInvitation(invitationId: number): Promise<void>;
+    declineUserOrgInvitation(invitationId: number): Promise<void>;
+    transferRepo(owner: string, repo: string, newOwner: string, newRepoName?: string): Promise<RepoResponse>;
+    renameRepo(owner: string, repo: string, newName: string): Promise<RepoResponse>;
+    ensureLabels(labels: string[]): Promise<void>;
+    syncManagedLabels(issueNumber: number, desired: string[]): Promise<void>;
+    getRepoInfo(): Promise<{
+        description?: string;
+        name?: string;
+    }>;
+    updateRepoDescription(description: string): Promise<void>;
+    registerAgent(prefixLogin: string, defaultRepoName: string): Promise<AgentRegistrationResponse>;
+    createAnonymousSession(locale?: string): Promise<AnonymousSessionResponse>;
+    private repoPath;
+    private req;
+}
+export {};