@elyracode/felagi 0.9.25

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.9.25] - 2026-08-03
+
+### Added
+- Initial release: Elyra Félagi integration. Tools for issues (list/search/read/create/update), comments (with agent mentions), time tracking (`felagi_log_time` with human durations, `felagi_time_entries` with source provenance), the stopwatch (`felagi_timer`), the knowledge base (`felagi_articles`), projects, agents, and agent runs (`felagi_run`, queue/list/get). Ships a `felagi` skill covering the API's semantics (id shapes, time provenance, one-clock timer, actor model) and `/felagi`, `/felagi-timer`, and `/felagi-log` commands. Configured via `FELAGI_URL` + `FELAGI_TOKEN` (environment or project `.env`).

package/README.md

@@ -0,0 +1,55 @@
+# @elyracode/felagi
+
+[Elyra Félagi](https://elyracode.com/docs/felagi) integration for Elyra. Félagi is a project portal where people and agents share one board — this extension puts issues, comments, time tracking, the stopwatch, the knowledge base, projects, and agent runs inside your Elyra session.
+
+## Install
+
+```
+elyra install npm:@elyracode/felagi
+```
+
+## Setup
+
+Create a token in Félagi under **Settings → API tokens** and paste the block it hands you into your project's `.env` (or export the variables):
+
+```
+FELAGI_URL=https://felagi.example.com
+FELAGI_TOKEN=fat_...
+```
+
+A read-only token works for everything except writes (which answer 403 with a message saying so).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `felagi_me` | Who the token acts as, its workspace and abilities |
+| `felagi_issues` | List/search issues: text, status, type, priority, project, assignee, labels (AND), cycle, `updated_since` |
+| `felagi_issue` | One issue in full, optionally with the comment thread and delivered artifacts |
+| `felagi_create_issue` | Create an issue (title required) |
+| `felagi_update_issue` | PATCH any subset of fields; assigning an agent queues a run |
+| `felagi_comment` | Comment on an issue; mentioning an agent hands it the thread |
+| `felagi_log_time` | Log time as a person says it: `2h 30m`, `1d`, `90m` |
+| `felagi_time_entries` | Read hours, filtered by mine/date range/issue/source |
+| `felagi_timer` | Stopwatch: status, start (switches cleanly), stop, discard |
+| `felagi_articles` | Search the team knowledge base; read full articles |
+| `felagi_projects` | List projects |
+| `felagi_agents` | List assignable agents with runtime status |
+| `felagi_run` | Queue an agent run on an issue; list/read runs with summary and cost |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/felagi` | Dashboard — my issues, running timer, workspace |
+| `/felagi-timer` | `/felagi-timer start ACM-231`, `stop`, `status`, `discard` |
+| `/felagi-log` | `/felagi-log ACM-231 2h30m traced the redirect loop` |
+
+## Behavior notes
+
+- Issue references accept both the human identifier (`ACM-231`) and the numeric id.
+- Time durations are written the way a person says them; `spent_on` defaults to today.
+- Hours are always the token owner's own — the API has no actor field for time, deliberately.
+- Starting a timer while one runs stops and logs the first; the tool reports what was banked.
+- The knowledge base (`felagi_articles`) is the endpoint worth knowing: the agent reads the team's runbook before it starts.
+- API reference: [elyracode.com/docs/felagi/api](https://elyracode.com/docs/felagi/api)

package/extensions/index.ts

@@ -0,0 +1,831 @@
+/**
+ * Elyra Félagi integration.
+ *
+ * Félagi is a project portal where people and agents share one board:
+ * issues, comments, time tracking (manual, stopwatch, and agent runs),
+ * a knowledge base, whiteboards, and agent runs. This extension talks to
+ * its REST API (/api/v1) with a personal token.
+ *
+ * Configuration (environment or the project's .env):
+ *   FELAGI_URL=https://felagi.example.com
+ *   FELAGI_TOKEN=fat_...
+ *
+ * API notes baked into this client (from the specification):
+ * - An issue's `id` in responses is the human identifier (ACM-231); the
+ *   URL accepts both the numeric key and the identifier.
+ * - GET /timer answers 200 with null data when nothing runs - not a 404.
+ * - Starting a timer stops and logs any running one; the response says so.
+ * - Time durations are written the way a person says them ("2h 30m").
+ * - Hours are always the token owner's own; there is no actor field.
+ * - 404 means "does not exist OR belongs to another workspace".
+ * - Enums grow inside v1; unknown values are passed through, never matched
+ *   exhaustively.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+interface FelagiConfig {
+	baseUrl: string;
+	token: string;
+}
+
+function loadEnv(cwd: string): Record<string, string> {
+	const envPath = join(cwd, ".env");
+	if (!existsSync(envPath)) return {};
+	const result: Record<string, string> = {};
+	for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq < 0) continue;
+		const key = trimmed.slice(0, eq).trim();
+		let value = trimmed.slice(eq + 1).trim();
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1);
+		}
+		result[key] = value;
+	}
+	return result;
+}
+
+function getConfig(cwd: string): FelagiConfig | null {
+	const env = loadEnv(cwd);
+	const baseUrl = process.env.FELAGI_URL || env.FELAGI_URL;
+	const token = process.env.FELAGI_TOKEN || env.FELAGI_TOKEN;
+	if (!baseUrl || !token) return null;
+	return { baseUrl: baseUrl.replace(/\/+$/, ""), token };
+}
+
+// ── HTTP client ─────────────────────────────────────────────────────────────
+
+interface FelagiResponse {
+	ok: boolean;
+	status: number;
+	data: unknown;
+	retryAfter?: string;
+}
+
+async function felagiFetch(config: FelagiConfig, method: string, path: string, body?: unknown): Promise<FelagiResponse> {
+	const url = `${config.baseUrl}/api/v1${path}`;
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${config.token}`,
+		Accept: "application/json",
+	};
+	if (body !== undefined) headers["Content-Type"] = "application/json";
+
+	const response = await fetch(url, {
+		method,
+		headers,
+		body: body !== undefined ? JSON.stringify(body) : undefined,
+		signal: AbortSignal.timeout(30_000),
+	});
+	const text = await response.text();
+	let data: unknown;
+	try {
+		data = text ? JSON.parse(text) : null;
+	} catch {
+		data = text;
+	}
+	return {
+		ok: response.ok,
+		status: response.status,
+		data,
+		retryAfter: response.headers.get("Retry-After") ?? undefined,
+	};
+}
+
+function ok(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {} };
+}
+
+function err(text: string) {
+	return { content: [{ type: "text" as const, text }], details: {}, isError: true as const };
+}
+
+function noConfig() {
+	return err(
+		"F\u00e9lagi is not configured. Set FELAGI_URL and FELAGI_TOKEN in the environment or the project's .env file. " +
+			"Create a token under Settings \u2192 API tokens in F\u00e9lagi.",
+	);
+}
+
+/** Map the documented error statuses to actionable messages. */
+function apiError(response: FelagiResponse): ReturnType<typeof err> {
+	const message =
+		typeof response.data === "object" && response.data !== null && "message" in response.data
+			? String((response.data as { message: unknown }).message)
+			: String(response.data ?? "");
+	switch (response.status) {
+		case 401:
+			return err(`401: the token is wrong, revoked, expired, or its owner left the workspace. ${message}`);
+		case 403:
+			return err(`403: this token is read-only and the request was a write. ${message}`);
+		case 404:
+			return err("404: no such record, or it belongs to another workspace (F\u00e9lagi deliberately answers both the same).");
+		case 422: {
+			const errors =
+				typeof response.data === "object" && response.data !== null && "errors" in response.data
+					? JSON.stringify((response.data as { errors: unknown }).errors)
+					: "";
+			return err(`422 validation error: ${message} ${errors}`);
+		}
+		case 429:
+			return err(`429 rate limited. Retry after ${response.retryAfter ?? "?"} seconds.`);
+		default:
+			return err(`HTTP ${response.status}: ${message}`);
+	}
+}
+
+// ── Formatters ──────────────────────────────────────────────────────────────
+
+/** Rich text comes back as sanitised HTML; strip it for terminal display. */
+function stripHtml(html: string): string {
+	return html
+		.replace(/<br\s*\/?>/gi, "\n")
+		.replace(/<\/(p|div|h[1-6]|li)>/gi, "\n")
+		.replace(/<[^>]+>/g, "")
+		.replace(/&amp;/g, "&")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#0?39;/g, "'")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+interface Actor {
+	type?: string;
+	id?: number;
+	name?: string;
+}
+
+function formatActor(actor: Actor | null | undefined): string {
+	if (!actor) return "unassigned";
+	return `${actor.name ?? "?"} (${actor.type ?? "?"})`;
+}
+
+interface Issue {
+	id?: string;
+	title?: string;
+	description?: string | null;
+	type?: string;
+	status?: string;
+	priority?: string;
+	project?: { id?: number; name?: string } | null;
+	epic?: { id?: string; title?: string } | null;
+	assignee?: Actor | null;
+	creator?: Actor | null;
+	start_date?: string | null;
+	due_date?: string | null;
+	estimate_minutes?: number | null;
+	spent_minutes?: number;
+	labels?: string[];
+	cycle?: { number?: number; starts_on?: string; ends_on?: string } | null;
+	carried_over?: number;
+	updated_at?: string;
+}
+
+function formatIssueLine(issue: Issue): string {
+	const parts = [`${issue.id}: ${issue.title}`];
+	parts.push(`[${issue.type ?? "?"}/${issue.status ?? "?"}/${issue.priority ?? "?"}]`);
+	if (issue.assignee) parts.push(`\u2192 ${formatActor(issue.assignee)}`);
+	return parts.join(" ");
+}
+
+function formatIssueFull(issue: Issue): string {
+	const lines: string[] = [];
+	lines.push(`# ${issue.id}: ${issue.title}`);
+	lines.push(`Type: ${issue.type ?? "?"} | Status: ${issue.status ?? "?"} | Priority: ${issue.priority ?? "?"}`);
+	if (issue.project?.name) lines.push(`Project: ${issue.project.name} (id ${issue.project.id})`);
+	if (issue.epic?.title) lines.push(`Epic: ${issue.epic.id} ${issue.epic.title}`);
+	lines.push(`Assignee: ${formatActor(issue.assignee)} | Creator: ${formatActor(issue.creator)}`);
+	if (issue.start_date || issue.due_date) lines.push(`Dates: ${issue.start_date ?? "\u2014"} \u2192 ${issue.due_date ?? "\u2014"}`);
+	const estimate = issue.estimate_minutes != null ? `${issue.estimate_minutes}m estimated` : "no estimate";
+	lines.push(`Time: ${issue.spent_minutes ?? 0}m spent (includes agent run time), ${estimate}`);
+	if (issue.labels && issue.labels.length > 0) lines.push(`Labels: ${issue.labels.join(", ")}`);
+	if (issue.cycle?.number != null) {
+		lines.push(`Cycle: ${issue.cycle.number} (${issue.cycle.starts_on} \u2192 ${issue.cycle.ends_on})`);
+	}
+	if (issue.carried_over) lines.push(`Carried over ${issue.carried_over} closed cycle(s)`);
+	if (issue.description) {
+		lines.push("");
+		lines.push(stripHtml(issue.description));
+	}
+	return lines.join("\n");
+}
+
+interface CollectionMeta {
+	total?: number;
+	current_page?: number;
+	last_page?: number;
+}
+
+function collectionFooter(data: unknown): string {
+	const meta = (data as { meta?: CollectionMeta })?.meta;
+	if (!meta || meta.total == null) return "";
+	if ((meta.last_page ?? 1) > 1) {
+		return `\n\n(${meta.total} total, page ${meta.current_page}/${meta.last_page})`;
+	}
+	return `\n\n(${meta.total} total)`;
+}
+
+function rows(data: unknown): Record<string, unknown>[] {
+	const list = (data as { data?: unknown })?.data;
+	return Array.isArray(list) ? (list as Record<string, unknown>[]) : [];
+}
+
+function record(data: unknown): Record<string, unknown> {
+	const item = (data as { data?: unknown })?.data;
+	return (item ?? {}) as Record<string, unknown>;
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	// ── Tool: felagi_me ──
+	elyra.registerTool({
+		name: "felagi_me",
+		label: "F\u00e9lagi: Who Am I",
+		description:
+			"Verify the F\u00e9lagi connection: who the token acts as, which workspace it names, and whether it can write. " +
+			"Use this first when other F\u00e9lagi calls fail, or to learn the workspace issue prefix.",
+		parameters: Type.Object({}),
+		execute: async (_id, _params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const response = await felagiFetch(config, "GET", "/me");
+			if (!response.ok) return apiError(response);
+			const me = record(response.data) as {
+				user?: { name?: string; email?: string };
+				workspace?: { name?: string; issue_prefix?: string };
+				role?: string;
+				token?: { name?: string; abilities?: string[]; expires_at?: string | null };
+				abilities?: string[];
+			};
+			const abilities = me.token?.abilities ?? me.abilities ?? [];
+			return ok(
+				[
+					`User: ${me.user?.name ?? "?"} (${me.user?.email ?? "?"})`,
+					`Workspace: ${me.workspace?.name ?? "?"} (issue prefix: ${me.workspace?.issue_prefix ?? "?"})`,
+					`Role: ${me.role ?? "?"}`,
+					`Token abilities: ${abilities.join(", ") || "?"}${abilities.includes("write") ? "" : " (read-only: writes will 403)"}`,
+				].join("\n"),
+			);
+		},
+	});
+
+	// ── Tool: felagi_issues ──
+	elyra.registerTool({
+		name: "felagi_issues",
+		label: "F\u00e9lagi: List Issues",
+		description:
+			"List and search F\u00e9lagi issues. Filter by free text (q, matches title and description), status " +
+			"(backlog/todo/in_progress/in_review/on_hold/done/canceled), type (epic/bug/feature/task/...), priority " +
+			"(urgent/high/medium/low), project_id, assignee, labels (multiple = AND), cycle (number, or 'none' for " +
+			"unplanned work), or updated_since for cheap polling.",
+		parameters: Type.Object({
+			q: Type.Optional(Type.String({ description: "Free-text search in title and description" })),
+			status: Type.Optional(Type.String()),
+			type: Type.Optional(Type.String()),
+			priority: Type.Optional(Type.String()),
+			project_id: Type.Optional(Type.Number()),
+			assignee_type: Type.Optional(Type.String({ description: "'user' or 'agent'" })),
+			assignee_id: Type.Optional(Type.Number()),
+			labels: Type.Optional(Type.Array(Type.String(), { description: "Multiple labels mean the overlap (AND)" })),
+			cycle: Type.Optional(Type.String({ description: "Cycle number, or 'none' for issues in no cycle" })),
+			updated_since: Type.Optional(Type.String({ description: "ISO timestamp; everything touched since" })),
+			per_page: Type.Optional(Type.Number({ description: "Up to 100 (default 25)" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const query = new URLSearchParams();
+			if (params.q) query.set("q", params.q);
+			if (params.status) query.set("status", params.status);
+			if (params.type) query.set("type", params.type);
+			if (params.priority) query.set("priority", params.priority);
+			if (params.project_id != null) query.set("project_id", String(params.project_id));
+			if (params.assignee_type) query.set("assignee_type", params.assignee_type);
+			if (params.assignee_id != null) query.set("assignee_id", String(params.assignee_id));
+			for (const label of params.labels ?? []) query.append("label", label);
+			if (params.cycle) query.set("cycle", params.cycle);
+			if (params.updated_since) query.set("updated_since", params.updated_since);
+			if (params.per_page != null) query.set("per_page", String(params.per_page));
+			const suffix = query.size > 0 ? `?${query.toString()}` : "";
+			const response = await felagiFetch(config, "GET", `/issues${suffix}`);
+			if (!response.ok) return apiError(response);
+			const issues = rows(response.data) as Issue[];
+			if (issues.length === 0) return ok("No issues match.");
+			return ok(issues.map((i) => `- ${formatIssueLine(i)}`).join("\n") + collectionFooter(response.data));
+		},
+	});
+
+	// ── Tool: felagi_issue ──
+	elyra.registerTool({
+		name: "felagi_issue",
+		label: "F\u00e9lagi: Read Issue",
+		description:
+			"Read one F\u00e9lagi issue in full, optionally with its comment thread and delivered artifacts " +
+			"(pull requests, branches, commits). Accepts the human identifier (ACM-231) or the numeric id.",
+		parameters: Type.Object({
+			issue: Type.String({ description: "Issue identifier (e.g. ACM-231) or numeric id" }),
+			include_comments: Type.Optional(Type.Boolean({ description: "Include the comment thread" })),
+			include_artifacts: Type.Optional(Type.Boolean({ description: "Include what runs delivered" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const issueRef = encodeURIComponent(params.issue);
+			const response = await felagiFetch(config, "GET", `/issues/${issueRef}`);
+			if (!response.ok) return apiError(response);
+			const parts = [formatIssueFull(record(response.data) as Issue)];
+
+			if (params.include_comments) {
+				const comments = await felagiFetch(config, "GET", `/issues/${issueRef}/comments`);
+				if (comments.ok) {
+					const list = rows(comments.data) as Array<{
+						author?: Actor;
+						body?: string;
+						from_run?: string | null;
+						created_at?: string;
+					}>;
+					parts.push("\n## Comments");
+					if (list.length === 0) parts.push("(none)");
+					for (const c of list) {
+						const runNote = c.from_run ? " [agent run report]" : "";
+						parts.push(`- ${formatActor(c.author)}${runNote} (${c.created_at ?? "?"}):\n  ${stripHtml(c.body ?? "").replace(/\n/g, "\n  ")}`);
+					}
+				}
+			}
+
+			if (params.include_artifacts) {
+				const artifacts = await felagiFetch(config, "GET", `/issues/${issueRef}/artifacts`);
+				if (artifacts.ok) {
+					const list = rows(artifacts.data) as Array<{
+						type?: string;
+						state?: string | null;
+						title?: string;
+						url?: string | null;
+						reference?: string | null;
+					}>;
+					parts.push("\n## Artifacts");
+					if (list.length === 0) parts.push("(none)");
+					for (const a of list) {
+						const state = a.state ? ` (${a.state})` : "";
+						parts.push(`- [${a.type}]${state} ${a.title ?? a.reference ?? ""} ${a.url ?? ""}`.trim());
+					}
+				}
+			}
+
+			return ok(parts.join("\n"));
+		},
+	});
+
+	// ── Tool: felagi_create_issue ──
+	elyra.registerTool({
+		name: "felagi_create_issue",
+		label: "F\u00e9lagi: Create Issue",
+		description: "Create a F\u00e9lagi issue. Only title is required. Requires a write token.",
+		parameters: Type.Object({
+			title: Type.String(),
+			description: Type.Optional(Type.String({ description: "HTML (sanitised server-side); plain text is fine" })),
+			type: Type.Optional(Type.String({ description: "epic/bug/feature/task/cosmetics/exception/..." })),
+			priority: Type.Optional(Type.String({ description: "urgent/high/medium/low" })),
+			project_id: Type.Optional(Type.Number()),
+			estimate_minutes: Type.Optional(Type.Number()),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const response = await felagiFetch(config, "POST", "/issues", params);
+			if (!response.ok) return apiError(response);
+			const issue = record(response.data) as Issue;
+			return ok(`Created ${issue.id}: ${issue.title}`);
+		},
+	});
+
+	// ── Tool: felagi_update_issue ──
+	elyra.registerTool({
+		name: "felagi_update_issue",
+		label: "F\u00e9lagi: Update Issue",
+		description:
+			"Update any subset of an issue's fields (PATCH semantics: omitted fields are left alone). " +
+			"Setting assignee_type='agent' queues a run for that agent, exactly like assigning it in the interface.",
+		parameters: Type.Object({
+			issue: Type.String({ description: "Issue identifier (e.g. ACM-231) or numeric id" }),
+			title: Type.Optional(Type.String()),
+			description: Type.Optional(Type.String()),
+			status: Type.Optional(Type.String({ description: "backlog/todo/in_progress/in_review/on_hold/done/canceled" })),
+			priority: Type.Optional(Type.String()),
+			type: Type.Optional(Type.String()),
+			assignee_type: Type.Optional(Type.String({ description: "'user' or 'agent' \u2014 agent queues a run" })),
+			assignee_id: Type.Optional(Type.Number()),
+			start_date: Type.Optional(Type.String({ description: "YYYY-MM-DD" })),
+			due_date: Type.Optional(Type.String({ description: "YYYY-MM-DD" })),
+			estimate_minutes: Type.Optional(Type.Number()),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const { issue, ...fields } = params;
+			const response = await felagiFetch(config, "PATCH", `/issues/${encodeURIComponent(issue)}`, fields);
+			if (!response.ok) return apiError(response);
+			const updated = record(response.data) as Issue;
+			return ok(`Updated ${updated.id}: ${formatIssueLine(updated)}`);
+		},
+	});
+
+	// ── Tool: felagi_comment ──
+	elyra.registerTool({
+		name: "felagi_comment",
+		label: "F\u00e9lagi: Comment",
+		description:
+			"Comment on a F\u00e9lagi issue. Mentioning an agent by name (e.g. '@Freya have a look') hands it the " +
+			"thread, exactly as from the interface.",
+		parameters: Type.Object({
+			issue: Type.String({ description: "Issue identifier (e.g. ACM-231) or numeric id" }),
+			body: Type.String(),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const response = await felagiFetch(config, "POST", `/issues/${encodeURIComponent(params.issue)}/comments`, {
+				body: params.body,
+			});
+			if (!response.ok) return apiError(response);
+			return ok(`Comment posted on ${params.issue}.`);
+		},
+	});
+
+	// ── Tool: felagi_log_time ──
+	elyra.registerTool({
+		name: "felagi_log_time",
+		label: "F\u00e9lagi: Log Time",
+		description:
+			"Log time on an issue the way a person says it: '2h 30m', '1d', '90m' (or minutes as a number). " +
+			"spent_on defaults to today \u2014 pass the day the work actually happened when logging late. " +
+			"Hours are always the token owner's own; there is no way to log against a colleague.",
+		parameters: Type.Object({
+			issue: Type.String({ description: "Issue identifier (e.g. ACM-231) or numeric id" }),
+			duration: Type.Optional(Type.String({ description: "'2h 30m', '1d', '90m'" })),
+			minutes: Type.Optional(Type.Number({ description: "Alternative to duration" })),
+			spent_on: Type.Optional(Type.String({ description: "YYYY-MM-DD, the day the work happened (default today)" })),
+			note: Type.Optional(Type.String({ description: "Plain text note" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			if (!params.duration && params.minutes == null) {
+				return err("Provide duration ('2h 30m') or minutes.");
+			}
+			const { issue, ...body } = params;
+			const response = await felagiFetch(config, "POST", `/issues/${encodeURIComponent(issue)}/time`, body);
+			if (!response.ok) return apiError(response);
+			const entry = record(response.data) as { minutes?: number; spent_on?: string };
+			return ok(`Logged ${entry.minutes ?? "?"}m on ${issue} (${entry.spent_on ?? "today"}).`);
+		},
+	});
+
+	// ── Tool: felagi_time_entries ──
+	elyra.registerTool({
+		name: "felagi_time_entries",
+		label: "F\u00e9lagi: Time Entries",
+		description:
+			"Read time entries. Filter by mine, date range (on spent_on \u2014 the day the work happened), issue, or " +
+			"source. Sources are different kinds of numbers: 'timer' is measured, 'manual' is remembered, " +
+			"'agent_run' is machine time \u2014 say which when summing.",
+		parameters: Type.Object({
+			mine: Type.Optional(Type.Boolean({ description: "Only the token owner's hours" })),
+			from: Type.Optional(Type.String({ description: "YYYY-MM-DD" })),
+			to: Type.Optional(Type.String({ description: "YYYY-MM-DD" })),
+			issue_id: Type.Optional(Type.Number()),
+			source: Type.Optional(Type.String({ description: "manual, timer, or agent_run" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const query = new URLSearchParams();
+			if (params.mine) query.set("mine", "1");
+			if (params.from) query.set("from", params.from);
+			if (params.to) query.set("to", params.to);
+			if (params.issue_id != null) query.set("issue_id", String(params.issue_id));
+			if (params.source) query.set("source", params.source);
+			const suffix = query.size > 0 ? `?${query.toString()}` : "";
+			const response = await felagiFetch(config, "GET", `/time-entries${suffix}`);
+			if (!response.ok) return apiError(response);
+			const entries = rows(response.data) as Array<{
+				id?: number;
+				issue?: string;
+				minutes?: number;
+				spent_on?: string;
+				source?: string;
+				note?: string | null;
+				actor?: Actor;
+			}>;
+			if (entries.length === 0) return ok("No time entries match.");
+			let total = 0;
+			const lines = entries.map((e) => {
+				total += e.minutes ?? 0;
+				const note = e.note ? ` \u2014 ${e.note}` : "";
+				return `- ${e.spent_on} ${e.issue}: ${e.minutes}m [${e.source}] ${formatActor(e.actor)}${note}`;
+			});
+			lines.push(`\nSum of listed entries: ${Math.floor(total / 60)}h ${total % 60}m (mixes sources unless filtered)`);
+			return ok(lines.join("\n") + collectionFooter(response.data));
+		},
+	});
+
+	// ── Tool: felagi_timer ──
+	elyra.registerTool({
+		name: "felagi_timer",
+		label: "F\u00e9lagi: Timer",
+		description:
+			"The stopwatch: one running clock per person. Actions: 'status' (what runs, or nothing \u2014 that is an " +
+			"answer, not an error), 'start' (on an issue; stops and logs any running timer, and says so), 'stop' " +
+			"(stops and writes the hours down), 'discard' (stops recording nothing). A forgotten timer is capped at " +
+			"8 hours server-side.",
+		parameters: Type.Object({
+			action: Type.Union([Type.Literal("status"), Type.Literal("start"), Type.Literal("stop"), Type.Literal("discard")]),
+			issue: Type.Optional(Type.String({ description: "Required for 'start': issue identifier or numeric id" })),
+			note: Type.Optional(Type.String({ description: "Optional note for 'start'" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+
+			if (params.action === "status") {
+				const response = await felagiFetch(config, "GET", "/timer");
+				if (!response.ok) return apiError(response);
+				const timer = (response.data as { data?: { issue?: string; started_at?: string; note?: string | null } | null })
+					?.data;
+				if (!timer) return ok("No timer is running.");
+				return ok(`Timer running on ${timer.issue} since ${timer.started_at}${timer.note ? ` \u2014 ${timer.note}` : ""}`);
+			}
+
+			if (params.action === "start") {
+				if (!params.issue) return err("'start' needs an issue.");
+				const response = await felagiFetch(config, "POST", `/issues/${encodeURIComponent(params.issue)}/timer`, {
+					note: params.note,
+				});
+				if (!response.ok) return apiError(response);
+				const payload = response.data as {
+					data?: { issue?: string; started_at?: string };
+					stopped?: { issue?: string; minutes?: number } | null;
+				};
+				const started = `Timer started on ${payload.data?.issue ?? params.issue}.`;
+				if (payload.stopped) {
+					return ok(`${started} Stopped and logged the previous one: ${payload.stopped.minutes}m on ${payload.stopped.issue}.`);
+				}
+				return ok(started);
+			}
+
+			if (params.action === "stop") {
+				const response = await felagiFetch(config, "POST", "/timer/stop");
+				if (!response.ok) return apiError(response);
+				const entry = record(response.data) as { issue?: string; minutes?: number };
+				return ok(`Timer stopped: logged ${entry.minutes ?? "?"}m on ${entry.issue ?? "?"}.`);
+			}
+
+			const response = await felagiFetch(config, "DELETE", "/timer");
+			if (!response.ok && response.status !== 204) return apiError(response);
+			return ok("Timer discarded; nothing was recorded.");
+		},
+	});
+
+	// ── Tool: felagi_articles ──
+	elyra.registerTool({
+		name: "felagi_articles",
+		label: "F\u00e9lagi: Knowledge Base",
+		description:
+			"Search and read the team's knowledge base \u2014 runbooks, conventions, decisions. Read the relevant " +
+			"article BEFORE starting work that the team has documented (deploys, restores, conventions). A search " +
+			"returns a table of contents (titles + excerpts); pass an article id to get the full body.",
+		parameters: Type.Object({
+			q: Type.Optional(Type.String({ description: "Search query (omit with article_id)" })),
+			article_id: Type.Optional(Type.String({ description: "ULID of one article \u2014 returns the full body" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+
+			if (params.article_id) {
+				const response = await felagiFetch(config, "GET", `/articles/${encodeURIComponent(params.article_id)}`);
+				if (!response.ok) return apiError(response);
+				const article = record(response.data) as { title?: string; body?: string; updated_at?: string };
+				return ok(`# ${article.title}\n(updated ${article.updated_at})\n\n${stripHtml(article.body ?? "")}`);
+			}
+
+			const query = new URLSearchParams();
+			if (params.q) query.set("q", params.q);
+			const suffix = query.size > 0 ? `?${query.toString()}` : "";
+			const response = await felagiFetch(config, "GET", `/articles${suffix}`);
+			if (!response.ok) return apiError(response);
+			const articles = rows(response.data) as Array<{
+				id?: string;
+				title?: string;
+				depth?: number;
+				excerpt?: string;
+			}>;
+			if (articles.length === 0) return ok("No articles match.");
+			const lines = articles.map((a) => `- ${"  ".repeat(a.depth ?? 0)}${a.title} (${a.id})\n  ${a.excerpt ?? ""}`);
+			lines.push("\nPass article_id to read a full article.");
+			return ok(lines.join("\n") + collectionFooter(response.data));
+		},
+	});
+
+	// ── Tool: felagi_projects ──
+	elyra.registerTool({
+		name: "felagi_projects",
+		label: "F\u00e9lagi: Projects",
+		description: "List F\u00e9lagi projects with status, priority, lead, and which issue types each offers.",
+		parameters: Type.Object({}),
+		execute: async (_id, _params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const response = await felagiFetch(config, "GET", "/projects");
+			if (!response.ok) return apiError(response);
+			const projects = rows(response.data) as Array<{
+				id?: number;
+				name?: string;
+				status?: string;
+				priority?: string;
+				lead?: Actor | null;
+				target_date?: string | null;
+				issue_types?: string[];
+			}>;
+			if (projects.length === 0) return ok("No projects.");
+			return ok(
+				projects
+					.map((p) => {
+						const target = p.target_date ? `, target ${p.target_date}` : "";
+						return `- [${p.id}] ${p.name} (${p.status}/${p.priority}${target}) lead: ${formatActor(p.lead)} types: ${(p.issue_types ?? []).join(", ")}`;
+					})
+					.join("\n") + collectionFooter(response.data),
+			);
+		},
+	});
+
+	// ── Tool: felagi_agents ──
+	elyra.registerTool({
+		name: "felagi_agents",
+		label: "F\u00e9lagi: Agents",
+		description:
+			"List the F\u00e9lagi agents you can assign work to, with provider, model, status, and whether their " +
+			"runtime machine is online.",
+		parameters: Type.Object({}),
+		execute: async (_id, _params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+			const response = await felagiFetch(config, "GET", "/agents");
+			if (!response.ok) return apiError(response);
+			const agents = rows(response.data) as Array<{
+				id?: number;
+				name?: string;
+				provider?: string;
+				model?: string | null;
+				status?: string;
+				runtime?: { name?: string; online?: boolean } | null;
+			}>;
+			if (agents.length === 0) return ok("No agents you can assign to.");
+			return ok(
+				agents
+					.map((a) => {
+						const runtime = a.runtime ? ` on ${a.runtime.name} (${a.runtime.online ? "online" : "offline"})` : "";
+						return `- [${a.id}] ${a.name}: ${a.provider}${a.model ? `/${a.model}` : ""}, ${a.status}${runtime}`;
+					})
+					.join("\n"),
+			);
+		},
+	});
+
+	// ── Tool: felagi_run ──
+	elyra.registerTool({
+		name: "felagi_run",
+		label: "F\u00e9lagi: Agent Runs",
+		description:
+			"Queue an agent run on an issue, or read runs. Actions: 'queue' (issue + agent_id; answers 202 \u2014 the " +
+			"run is queued, whether a machine picks it up depends on a daemon), 'list' (filter by status/agent_id), " +
+			"'get' (one run by ULID, with summary, error, and usage).",
+		parameters: Type.Object({
+			action: Type.Union([Type.Literal("queue"), Type.Literal("list"), Type.Literal("get")]),
+			issue: Type.Optional(Type.String({ description: "For 'queue': issue identifier or numeric id" })),
+			agent_id: Type.Optional(Type.Number({ description: "For 'queue' (required) and 'list' (filter)" })),
+			run_id: Type.Optional(Type.String({ description: "For 'get': the run's ULID" })),
+			status: Type.Optional(Type.String({ description: "For 'list': queued/dispatched/running/completed/failed/canceled" })),
+		}),
+		execute: async (_id, params, _signal, _onUpdate, ctx) => {
+			const config = getConfig(ctx.cwd);
+			if (!config) return noConfig();
+
+			if (params.action === "queue") {
+				if (!params.issue || params.agent_id == null) return err("'queue' needs issue and agent_id.");
+				const response = await felagiFetch(config, "POST", `/issues/${encodeURIComponent(params.issue)}/runs`, {
+					agent_id: params.agent_id,
+				});
+				if (!response.ok) return apiError(response);
+				return ok(`Run queued on ${params.issue} (202: whether a machine picks it up depends on the daemon).`);
+			}
+
+			if (params.action === "get") {
+				if (!params.run_id) return err("'get' needs run_id.");
+				const response = await felagiFetch(config, "GET", `/runs/${encodeURIComponent(params.run_id)}`);
+				if (!response.ok) return apiError(response);
+				const run = record(response.data) as {
+					id?: string;
+					status?: string;
+					agent?: { name?: string };
+					issue?: string | null;
+					attempts?: number;
+					finished_at?: string | null;
+					error?: string | null;
+					summary?: string | null;
+					usage?: { cost_usd?: number | null } | null;
+				};
+				const lines = [
+					`Run ${run.id}: ${run.status} (agent: ${run.agent?.name ?? "?"}, issue: ${run.issue ?? "\u2014"}, attempts: ${run.attempts ?? "?"})`,
+				];
+				if (run.finished_at) lines.push(`Finished: ${run.finished_at}`);
+				if (run.error) lines.push(`Error: ${run.error}`);
+				if (run.summary) lines.push(`Summary: ${run.summary}`);
+				if (run.usage?.cost_usd != null) lines.push(`Cost: $${run.usage.cost_usd}`);
+				return ok(lines.join("\n"));
+			}
+
+			const query = new URLSearchParams();
+			if (params.status) query.set("status", params.status);
+			if (params.agent_id != null) query.set("agent_id", String(params.agent_id));
+			const suffix = query.size > 0 ? `?${query.toString()}` : "";
+			const response = await felagiFetch(config, "GET", `/runs${suffix}`);
+			if (!response.ok) return apiError(response);
+			const runs = rows(response.data) as Array<{
+				id?: string;
+				status?: string;
+				agent?: { name?: string };
+				issue?: string | null;
+				finished_at?: string | null;
+			}>;
+			if (runs.length === 0) return ok("No runs match.");
+			return ok(
+				runs
+					.map((r) => `- ${r.id} [${r.status}] agent: ${r.agent?.name ?? "?"}, issue: ${r.issue ?? "\u2014"}`)
+					.join("\n") + collectionFooter(response.data),
+			);
+		},
+	});
+
+	// ── Commands ────────────────────────────────────────────────────────────
+
+	elyra.registerCommand("felagi", {
+		description: "F\u00e9lagi dashboard \u2014 my issues, running timer, workspace",
+		handler: async (_args, _ctx) => {
+			elyra.sendUserMessage(
+				"Show my F\u00e9lagi status: who I am (felagi_me), my open issues (felagi_issues with assignee_type=user " +
+					"and my id from felagi_me, status in_progress then todo), and whether a timer is running (felagi_timer status).",
+			);
+		},
+	});
+
+	elyra.registerCommand("felagi-timer", {
+		description: "F\u00e9lagi stopwatch: /felagi-timer [start <issue>|stop|status|discard]",
+		handler: async (args, _ctx) => {
+			const trimmed = args.trim();
+			if (!trimmed || trimmed === "status") {
+				elyra.sendUserMessage("Check the F\u00e9lagi timer status (felagi_timer action=status) and tell me what is running.");
+				return;
+			}
+			if (trimmed === "stop") {
+				elyra.sendUserMessage("Stop the F\u00e9lagi timer (felagi_timer action=stop) and tell me what was logged.");
+				return;
+			}
+			if (trimmed === "discard") {
+				elyra.sendUserMessage("Discard the F\u00e9lagi timer (felagi_timer action=discard) without recording anything.");
+				return;
+			}
+			if (trimmed.startsWith("start ")) {
+				const issue = trimmed.slice(6).trim();
+				elyra.sendUserMessage(`Start the F\u00e9lagi timer on issue ${issue} (felagi_timer action=start).`);
+				return;
+			}
+			elyra.sendUserMessage(`Interpret this as a F\u00e9lagi timer request and use the felagi_timer tool: ${trimmed}`);
+		},
+	});
+
+	elyra.registerCommand("felagi-log", {
+		description: "Log time in F\u00e9lagi: /felagi-log <issue> <duration> [note]",
+		handler: async (args, ctx) => {
+			const match = args.trim().match(/^(\S+)\s+(\S+(?:\s+\d+m)?)\s*(.*)$/);
+			if (!match) {
+				ctx.ui.notify("Usage: /felagi-log <issue> <duration> [note] \u2014 e.g. /felagi-log ACM-231 2h30m traced the loop", "error");
+				return;
+			}
+			const [, issue, duration, note] = match;
+			elyra.sendUserMessage(
+				`Log time in F\u00e9lagi with felagi_log_time: issue ${issue}, duration "${duration}"${note ? `, note "${note}"` : ""}.`,
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@elyracode/felagi",
+  "version": "0.9.25",
+  "description": "Elyra Félagi integration — issues, comments, time tracking, the stopwatch, knowledge base, projects, and agent runs from your Elyra session",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "felagi",
+    "issues",
+    "time-tracking",
+    "project-management"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/felagi"
+  },
+  "elyra": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/felagi/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: felagi
+description: Elyra Félagi project portal integration. Use when the user mentions Félagi, their issue board, logging time/hours, the stopwatch/timer, issue identifiers like ACM-231, the team knowledge base, or queueing agent runs.
+---
+
+# Félagi
+
+Félagi is the team's project portal: people and agents share one board. Issues, comments, time tracking, a knowledge base, and agent runs are all reachable over its API.
+
+## When to Use
+
+- The user references an issue identifier (`ACM-231` style) or asks what's on their plate
+- The user wants to log hours, start/stop a timer, or review a timesheet
+- Work is starting that the team may have documented (deploys, restores, conventions) — check the knowledge base first
+- The user wants to create/update issues, comment, or hand work to a Félagi agent
+
+## Available Tools
+
+| Tool | Use for |
+|------|---------|
+| `felagi_me` | Verify connection, workspace, token abilities. Run first when things fail |
+| `felagi_issues` | List/search issues (q, status, type, priority, project, assignee, labels, cycle, updated_since) |
+| `felagi_issue` | One issue in full, optionally with comments and delivered artifacts |
+| `felagi_create_issue` | New issue (title required) |
+| `felagi_update_issue` | PATCH any subset; `assignee_type=agent` queues a run |
+| `felagi_comment` | Comment; mentioning an agent by name hands it the thread |
+| `felagi_log_time` | Log a duration the way a person says it: "2h 30m", "1d", "90m" |
+| `felagi_time_entries` | Read hours (mine/from/to/issue/source) |
+| `felagi_timer` | The stopwatch: status/start/stop/discard |
+| `felagi_articles` | Search and read the team knowledge base |
+| `felagi_projects` | List projects |
+| `felagi_agents` | List assignable agents and whether their runtime is online |
+| `felagi_run` | Queue a run on an issue; list/read runs |
+
+## Setup
+
+Requires `FELAGI_URL` and `FELAGI_TOKEN` (environment or project `.env`). Tokens are created under **Settings → API tokens** in Félagi; a read-only token makes every write answer 403.
+
+## Semantics Worth Respecting
+
+**Knowledge base before conventions-sensitive work.** Skills are what an agent is given; the knowledge base is what it can look up. `felagi_articles` with a query, then read the matching article's body, before deploys/restores/anything the team documents.
+
+**Issue ids are human.** Responses carry `ACM-231`, and the tools accept either that identifier or the numeric id. Use the identifier when talking to the user — it is what people say out loud.
+
+**Time has provenance.** `timer` is measured, `manual` is remembered, `agent_run` is machine time. Never sum sources without saying which — a mixed total is a guess.
+
+**Hours are always the token owner's own.** There is no way to log time for someone else; do not try to work around it.
+
+**The timer is one clock per person.** Starting a second stops and logs the first (the tool reports what was banked). "No timer running" is an answer, not an error. Forgotten timers are capped at 8h server-side.
+
+**People and agents share one shape.** `{ type: "user"|"agent", id, name }`. Do not special-case agents. `null` assignee means unassigned; "Former member" means a deleted account.
+
+**Two ways to put a Félagi agent to work.** Assign it (`felagi_update_issue` with `assignee_type=agent`) or mention it in a comment ("@Freya the build is failing — have a look"). The mention leaves a sentence explaining why, which the agent then reads — prefer it when context matters.
+
+**Enums grow.** Status/type/priority values may gain new members inside API v1; pass unknown values through rather than treating them as errors.
+
+**404 is deliberate.** "No such record" and "belongs to another workspace" answer identically. Do not retry a 404 with variations hoping to find a hidden record.
+
+## Typical Flows
+
+**Morning**: `felagi_issues` (assignee_type=user, own id from `felagi_me`, status=todo) → pick one → `felagi_timer` start → `felagi_update_issue` status=in_progress.
+
+**Done with a task**: `felagi_timer` stop → `felagi_comment` what happened → `felagi_update_issue` status=in_review.
+
+**Logging forgotten hours**: `felagi_log_time` with `spent_on` set to the day the work actually happened, not today.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/felagi` | Dashboard: who am I, my issues, running timer |
+| `/felagi-timer` | `start <issue>`, `stop`, `status`, `discard` |
+| `/felagi-log` | `/felagi-log ACM-231 2h30m traced the loop` |