@aion0/forge 0.8.1 → 0.8.3

package/lib/help-docs/21-build-connector.md

@@ -0,0 +1,314 @@
+# Build Your Own Connector
+
+This doc tells the Forge Help AI how to author a custom connector for
+the user. The user asks something like _"build me a connector for
+JIRA"_ or _"add a connector that scrapes my internal wiki"_; you walk
+them through requirements, generate a manifest, and install it locally.
+
+## Mental model
+
+A connector is a YAML manifest that exposes **tools** the chat LLM
+can call. Each tool runs in one of three places:
+
+| `protocol` | Where it runs | Used for |
+|---|---|---|
+| `browser` (default) | User's tab, via the Forge browser extension | DOM-scraping the user's logged-in UI (Mantis, GitLab UI, Teams) |
+| `http` | Forge server | Clean REST APIs with PAT auth (GitHub, Stripe, …) |
+| `shell` | Forge server | Local CLI tools (`git`, `gh`, `kubectl`, …) |
+
+Choose **browser** when the user is already logged in to a web app and
+you don't want to manage tokens. Choose **http** when there's a clean
+REST API. Choose **shell** when wrapping a local CLI.
+
+## The interview (ask the user)
+
+Before writing anything, ask:
+
+1. **What service / site?** (e.g. JIRA Server at jira.acme.com)
+2. **What actions are needed?** Read-only? Read + write? List of verbs.
+3. **Auth?** Logged-in browser session, PAT, OAuth, local CLI?
+4. **What settings does the user need to fill in?** (base_url, PAT, default project, …)
+
+Stop after this; show the user a one-paragraph plan; let them adjust.
+
+## Manifest shape
+
+Required fields: `id`, `name`, `version`, and either `tools` or
+`connectors[]`. Everything else is optional.
+
+```yaml
+id: jira                       # lowercase, alphanumerics + - / _
+name: JIRA
+icon: "📋"
+version: "0.1.0"
+author: "<user-provided>"
+description: |
+  Multi-line description shown in the marketplace.
+
+# Optional. Locks install to Forge versions that have the required runtime features.
+min_forge_version: "0.8.0"
+
+# Browser runner. Default 'main'. Use 'isolated' for strict-CSP
+# sites (Teams, github.com) that block eval in the page world.
+runner: main
+
+# Per-user settings rendered as a form in Settings → Connectors.
+settings:
+  base_url:
+    type: string
+    label: JIRA base URL
+    required: true
+  token:
+    type: secret              # encrypted at rest (AES-256-GCM)
+    label: Personal access token
+    description: Create at <base_url>/secure/ViewProfile.jspa
+
+# Where the extension finds the authenticated tab. {settings.*} expanded server-side.
+host_match: "{base_url}/*"
+
+# Substring detected after navigation → "user not logged in".
+login_redirect: "/login.jsp"
+
+tools:
+  list_my_issues:
+    description: List JIRA issues assigned to me.
+    parameters:
+      project: { type: string, description: "Limit to one project key (optional)" }
+      status:  { type: select, options: ["open","done","all"], default: "open" }
+      limit:   { type: number, default: 25 }
+    # protocol omitted → browser
+    page:
+      url: "{base_url}/issues/?jql=assignee=currentUser()"
+      on_target: "/issues/"   # skip navigation if URL already matches
+    script: |
+      const rows = Array.from(document.querySelectorAll('.issuerow'));
+      return rows.slice(0, args.limit).map(r => ({
+        key:     r.dataset.issuekey,
+        title:   r.querySelector('.summary')?.textContent?.trim(),
+        status:  r.querySelector('.status')?.textContent?.trim(),
+        link:    r.querySelector('a.issue-link')?.href,
+      }));
+
+  add_comment:
+    destructive: true          # extension prompts before running
+    description: Add a comment to a JIRA issue.
+    parameters:
+      issue_key: { type: string, required: true }
+      text:      { type: string, required: true }
+    page:
+      url: "{base_url}/browse/{args.issue_key}"
+    script: |
+      // Same-origin fetch with user's session cookie auto-attached
+      const r = await fetch(`/rest/api/2/issue/${args.issue_key}/comment`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ body: args.text }),
+      });
+      if (!r.ok) return { _error: `HTTP ${r.status}: ${await r.text()}` };
+      return { ok: true };
+```
+
+### Template tokens
+
+- `{base_url}`, `{settings.<name>}` — expanded server-side at API
+  response time from the user's saved settings.
+- `{args.<name>}` — expanded at runtime from the LLM's tool input.
+  In a `script` body, prefer `args.foo` (a JS identifier) over the
+  literal `{args.foo}` string.
+
+### `script` contract
+
+- Receives `args` (the LLM's parsed parameters).
+- Returns a JSON-serialisable value (no DOM nodes, no functions).
+- Has access to `document`, `fetch`, `URL`, `Headers`, etc. (page context).
+- Same-origin `fetch()` — the user's session cookies attach automatically.
+- Must be **self-contained** — no closures over Forge / extension code,
+  no `import`, no `require`.
+- Throws are caught by the runner and surfaced as tool errors;
+  prefer `return { _error: '...' }` for predictable failure messages.
+
+### http protocol
+
+For services with a clean REST API:
+
+```yaml
+tools:
+  get_repo:
+    protocol: http
+    parameters:
+      owner: { type: string, required: true }
+      repo:  { type: string, required: true }
+    request:
+      method: GET
+      url: "https://api.github.com/repos/{args.owner}/{args.repo}"
+      headers:
+        Accept: "application/vnd.github+json"
+        Authorization: "Bearer {settings.token}"
+    timeout_ms: 15000
+```
+
+### test block
+
+A connector can ship a self-test so the Settings → Connectors UI's
+**Test** button has something to call. Two probe kinds:
+
+**`probe: http`** (default) — server issues a one-shot HTTP request
+with `{settings.*}` expanded. Use for REST-API connectors with a
+quick `/me`-style endpoint.
+
+```yaml
+test:
+  description: "GET /api/v4/user — verifies token works"
+  probe: http
+  request:
+    method: GET
+    url: "{settings.base_url}/api/v4/user"
+    headers:
+      PRIVATE-TOKEN: "{settings.token}"
+  ok_status: [200]                              # default [200]
+  ok_template: "Authenticated as {{username}} ({{name}})"
+  timeout_ms: 15000                              # default 15s
+```
+
+`ok_template` accepts `{{<json-path>}}` placeholders that resolve
+against the parsed response body. Missing paths render `?`.
+
+**`probe: browser`** — forwarded to the paired Forge browser
+extension. The extension opens / acquires a tab matching
+`host_match`, waits for navigation, and reports whether the final
+URL contains `login_redirect`. Use for browser-side connectors
+(Mantis, Teams, PMDB) where auth is the user's session cookie
+rather than a token Forge can verify server-side.
+
+```yaml
+test:
+  description: "Opens a Mantis tab and checks the session is alive."
+  probe: browser
+  timeout_ms: 30000                              # default 30s
+```
+
+No `request:` needed — the probe reuses the manifest's top-level
+`host_match` + `login_redirect`.
+
+**Extension wire contract** (for extension implementers):
+
+```ts
+// bridge method: 'connector.probe'
+// params:
+{
+  pluginId: string;
+  host_match: string;          // expanded with {settings.*}
+  login_redirect?: string;     // expanded with {settings.*}
+  runner: 'main' | 'isolated'; // inherits from manifest.runner
+  timeout_ms: number;          // honour or cap, your call
+}
+// response:
+{ ok: true,  url: '<final tab URL>' }
+{ ok: false, error: 'login required' | '<other>', url?: string }
+```
+
+The extension's existing tab-acquisition logic already knows how
+to handle `host_match` + `login_redirect`; the probe just runs the
+acquire step and skips `executeScript`. If the extension isn't
+connected, the Forge route surfaces a clear "install + sign in to
+the Forge extension" message.
+
+### shell protocol
+
+For local CLI tools. **Every arg is templated independently** — no
+shell injection.
+
+```yaml
+tools:
+  git_log:
+    protocol: shell
+    parameters:
+      repo: { type: string, required: true }
+      n:    { type: number, default: 20 }
+    command: ['git', '-C', '{args.repo}', 'log', '-n', '{args.n}', '--oneline']
+    timeout_ms: 5000
+```
+
+## How you, the AI, install it
+
+You have direct filesystem access to the running user's Forge data
+directory. There are two paths:
+
+### Path A — write the manifest directly (preferred for AI)
+
+Find the data directory (usually `~/.forge/data/`, override via
+`FORGE_DATA_DIR` env). Write:
+
+```
+<dataDir>/connectors/<id>/manifest.yaml
+```
+
+…then call the install-local API to register it:
+
+```bash
+curl -s -X POST http://localhost:8403/api/connectors/install-local \
+  -H "X-Forge-Token: $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -nc --arg yaml "$(cat <dataDir>/connectors/<id>/manifest.yaml)" '{yaml: $yaml}')"
+```
+
+(See `lib/help-docs/CLAUDE.md` for the auth pattern.)
+
+### Path B — generate a zip for hand-installation
+
+If the user wants to share the connector with a colleague or store
+it in version control, package it as a zip:
+
+```
+my-connector.zip
+├── manifest.yaml
+├── README.md          (optional)
+├── icon.svg           (optional)
+└── tools/             (optional — separate files when scripts grow long)
+    └── list_my_issues.js
+```
+
+`manifest.yaml` must be at the root. The user then uploads via the
+"+ Upload" button in Settings → Connectors (or drags-and-drops onto
+the panel).
+
+## Checklist before declaring done
+
+- [ ] `id` is lowercase + URL-safe
+- [ ] At least one tool defined
+- [ ] `description` reads like one a stranger would understand
+- [ ] `version: "0.1.0"` (or whatever the user specifies)
+- [ ] `host_match` + `login_redirect` set for browser connectors
+- [ ] Settings include any secrets as `type: secret` (encrypted at rest)
+- [ ] Run a 1-tool smoke test by triggering the chat agent to call it,
+      and surface any error to the user
+- [ ] Tell the user where the manifest was saved + that they can edit
+      it under `<dataDir>/connectors/<id>/manifest.yaml`
+
+## Iterating
+
+When the user reports a bug ("the list_my_issues tool returned 0 rows"):
+
+1. Open the page they were on (they can navigate, you can suggest URLs).
+2. Use the browser extension's DOM inspector (or `mcp__chrome__` if
+   available) to find a stable selector.
+3. Edit the script body in the manifest. Bump `version` (patch bump).
+4. Tell the user to either close + reopen the Settings panel
+   ("Refresh" in Connectors), or just re-invoke the tool — the
+   extension picks up the new manifest on next call.
+
+## Limits and gotchas
+
+- Browser scripts cannot use Chrome extension APIs (`chrome.*`) — only
+  page-context globals.
+- For sites that virtualise lists (react-window, ag-grid), scroll
+  programmatically inside the script before scraping; otherwise you
+  only see what's currently in the DOM.
+- For strict-CSP sites (Teams, github.com), pure `eval` is blocked.
+  Use `runner: isolated` (which the extension's MV3 sandbox enables)
+  but you lose access to `window` globals (MSAL tokens, etc.) — stick
+  to pure DOM extraction.
+- If a connector breaks after a site redesign, only the YAML's
+  `script` body needs to change. Bump version, save, retry — the
+  registry-based update path is for connectors that came from a
+  shared `forge-connectors` repo.

package/lib/help-docs/CLAUDE.md

@@ -46,7 +46,8 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `13-ide-plugins.md` | VSCode extension + IntelliJ plugin — install, tabs, multi-connection, agent terminal launching |
 | `15-crafts.md` | Crafts — project-scoped mini-app tabs with SDK; AI-generated via "+ Craft" button |
 | `16-gitlab-autofix.md` | GitLab issue auto-fix — worktree + base-branch rule + Premium epic context + image attachments |
-| `17-connectors.md` | Browser extension connectors — plugin schema, HTTP API, settings sync, Mantis + GitLab built-ins |
+| `17-connectors.md` | Connectors — independent subsystem, marketplace fetched from `forge-connectors` registry, no built-ins. Manifest schema, HTTP API, install/update flow, pre-v0.9 migration. |
+| `21-build-connector.md` | **Authoring** a custom connector — interview script, manifest template (browser / http / shell protocols), how to install locally via the Forge data dir or a zip upload. Use this when the user asks to BUILD a connector, not when they ask about an existing one. |
 | `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
 | `19-jobs.md` | Jobs — scheduled connector polls that dedup and fan out to Pipeline / Chat |
 | `20-mantis-bug-fix.md` | Mantis → Bug Fix → MR builtin pipeline (mantis-bug-fix-and-mr) |
@@ -75,7 +76,8 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - vsce/vsix/JetBrains marketplace publish → `13-ide-plugins.md`
 - Craft/custom tab/mini-app/extend project/AI-generated tab/builder → `15-crafts.md`
 - GitLab/glab/MR/merge request/issue auto-fix/epic → `16-gitlab-autofix.md`
-- Connector/browser extension/plugin schema/Mantis/category=connector → `17-connectors.md`
+- Connector/connector marketplace/install connector/forge-connectors registry/Mantis manifest → `17-connectors.md`
+- Build / author / write / create a new connector / "make me a connector for X" / custom connector → `21-build-connector.md`
 - Chrome MCP / chrome-devtools-mcp / dev-time browser / CDP / remote debugging → `18-chrome-mcp.md`
 - Job / scheduled job / connector poll / dedup / periodic fetch / Teams poll / Mantis bug poll → `19-jobs.md`
 - Mantis bug fix pipeline / mantis-bug-fix-and-mr / open MR for Mantis bug / notify Teams from pipeline / connector-tool endpoint → `20-mantis-bug-fix.md`

package/lib/init.ts

@@ -133,6 +133,31 @@ export function ensureInitialized() {
     setInterval(() => { syncSkills().catch(() => {}); }, 60 * 60 * 1000);
   } catch {}
 
+  // One-shot migration: move pre-existing connector rows out of the
+  // plugin registry and into <dataDir>/connectors/. Idempotent — safe
+  // to call on every boot. Must run BEFORE syncRegistry so the
+  // migrated rows are visible to the sync layer (which uses
+  // installed_version to decide what to refresh).
+  try {
+    time('migrateConnectorConfigs', () => {
+      const { migrateConnectorConfigs } = require('./connectors/migration');
+      migrateConnectorConfigs();
+    });
+  } catch (err) {
+    console.warn('[connectors] migration failed:', err);
+  }
+
+  // Sync connectors registry (async, non-blocking). Refresh installed
+  // manifests in case the user has older versions on disk. Same cadence
+  // as skills.
+  try {
+    const { syncRegistry } = require('./connectors/sync');
+    syncRegistry({ refreshInstalled: true }).catch(() => {});
+    setInterval(() => {
+      syncRegistry({ refreshInstalled: true }).catch(() => {});
+    }, 60 * 60 * 1000);
+  } catch {}
+
   // Usage scanner — defer to next tick so it doesn't block ensureInitialized().
   // On a host with hundreds of project dirs in ~/.claude/projects/, the
   // synchronous readdirSync + statSync loop can take 5-10s; running it on

package/lib/jobs/dispatcher.ts

@@ -58,7 +58,12 @@ function renderTemplateMap(map: Record<string, string>, item: unknown): Record<s
  * slot). Letting pipeline_runs.dedup_key be NULL means each dispatch
  * gets its own row.
  */
-export function dispatchToPipeline(params: PipelineDispatchParams, item: unknown, _dedupKey: string): { target_id: string; rendered_input: Record<string, string>; empty_keys: string[] } {
+export function dispatchToPipeline(
+  params: PipelineDispatchParams,
+  item: unknown,
+  _dedupKey: string,
+  opts: { skills?: string[] } = {},
+): { target_id: string; rendered_input: Record<string, string>; empty_keys: string[] } {
   const renderedInput = renderTemplateMap(params.input_template || {}, item);
   // Heads-up if a template key rendered to empty — almost always means the
   // user wrote {{item.foo}} but the item has no 'foo' field. The pipeline
@@ -80,7 +85,8 @@ export function dispatchToPipeline(params: PipelineDispatchParams, item: unknown
     params.project_name,
     params.workflow_name,
     renderedInput,
-    // intentionally no dedup_key — see comment above
+    /* dedupKey */ undefined,        // intentionally no dedup_key — see comment above
+    { skills: opts.skills },
   );
   return { target_id: result.pipelineId, rendered_input: renderedInput, empty_keys: emptyKeys };
 }
@@ -114,7 +120,12 @@ async function getMainSessionId(): Promise<string> {
  */
 const reusedSessionByJob = new Map<string, string>();
 
-export async function dispatchToChat(params: ChatDispatchParams, item: unknown, jobId: string): Promise<{ target_id: string }> {
+export async function dispatchToChat(
+  params: ChatDispatchParams,
+  item: unknown,
+  jobId: string,
+  opts: { skills?: string[] } = {},
+): Promise<{ target_id: string }> {
   let sessionId: string | undefined;
   if (params.target === 'main') {
     sessionId = await getMainSessionId();
@@ -136,9 +147,15 @@ export async function dispatchToChat(params: ChatDispatchParams, item: unknown,
     if (params.reuse_session) reusedSessionByJob.set(jobId, sessionId);
   }
 
-  const text = renderTemplate(params.message_template, item);
-  if (!text.trim()) throw new Error('rendered chat message is empty');
-  await chatHttp(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, { text });
+  const rendered = renderTemplate(params.message_template, item);
+  if (!rendered.trim()) throw new Error('rendered chat message is empty');
+  // Skills get prepended as a one-line directive in the chat message —
+  // the chat agent picks them up the same way the user would by typing
+  // /skill-name themselves.
+  const skillsPrefix = opts.skills && opts.skills.length
+    ? `Use these Forge skills as appropriate for this task: ${opts.skills.map(s => '/' + s).join(', ')}.\n\n`
+    : '';
+  await chatHttp(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, { text: skillsPrefix + rendered });
   return { target_id: sessionId };
 }
 
@@ -158,7 +175,7 @@ export async function dispatchToChatSummary(
   params: ChatDispatchParams,
   items: unknown[],
   jobId: string,
-  opts: { totalMatching?: number | string | null } = {},
+  opts: { totalMatching?: number | string | null; skills?: string[] } = {},
 ): Promise<{ target_id: string; count: number }> {
   let sessionId: string | undefined;
   // Default target for summary mode is the main chat — that's where the
@@ -208,7 +225,10 @@ export async function dispatchToChatSummary(
   text = renderTemplate(text, items[0] ?? {});
 
   if (!text.trim()) throw new Error('rendered chat summary message is empty');
-  await chatHttp(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, { text });
+  const skillsPrefix = opts.skills && opts.skills.length
+    ? `Use these Forge skills as appropriate for this task: ${opts.skills.map(s => '/' + s).join(', ')}.\n\n`
+    : '';
+  await chatHttp(`/api/sessions/${encodeURIComponent(sessionId)}/messages`, { text: skillsPrefix + text });
   return { target_id: sessionId, count: items.length };
 }
 

package/lib/jobs/scheduler.ts

@@ -50,11 +50,53 @@ async function tick(): Promise<void> {
   }
 }
 
+function toSqlIso(d: Date): string {
+  return d.toISOString().replace('T', ' ').slice(0, 19);
+}
+
+/**
+ * Compute and store the job's next_run_at based on schedule_kind.
+ * For 'once' jobs we also auto-disable after the firing tick so they
+ * don't fire repeatedly when their schedule_at time is in the past.
+ */
 function advanceSchedule(job: Job): void {
-  const next = new Date(Date.now() + Math.max(1, job.schedule_interval_minutes) * 60_000);
-  // setNextRunAt also bumps last_run_at — call updateJob via raw SQL for clarity.
   const { setNextRunAt } = require('./store') as typeof import('./store');
-  setNextRunAt(job.id, next.toISOString().replace('T', ' ').slice(0, 19));
+  const now = Date.now();
+
+  if (job.schedule_kind === 'manual') {
+    // Manual jobs are filtered out of getDueJobs and should never get
+    // here. Belt-and-suspenders: clear any stray next_run_at.
+    setNextRunAt(job.id, null);
+    return;
+  }
+
+  if (job.schedule_kind === 'once') {
+    // One-shot: this tick is the fire. Disable for future, no next run.
+    setNextRunAt(job.id, null);
+    try { updateJob(job.id, { enabled: false }); } catch (e) {
+      console.warn(`[jobs] failed to auto-disable one-shot ${job.id}:`, e);
+    }
+    return;
+  }
+
+  if (job.schedule_kind === 'cron' && job.schedule_cron) {
+    try {
+      const { CronExpressionParser } = require('cron-parser');
+      const iter = CronExpressionParser.parse(job.schedule_cron, { currentDate: new Date(now) });
+      const next = iter.next().toDate();
+      setNextRunAt(job.id, toSqlIso(next));
+      return;
+    } catch (e) {
+      console.warn(`[jobs] cron parse failed for ${job.id} (expr "${job.schedule_cron}"):`, (e as Error).message);
+      // Fall through to period-style backoff so a broken cron doesn't
+      // tight-loop the tick.
+    }
+  }
+
+  // Default / 'period' path.
+  const minutes = Math.max(1, job.schedule_interval_minutes || 30);
+  const next = new Date(now + minutes * 60_000);
+  setNextRunAt(job.id, toSqlIso(next));
 }
 
 /**
@@ -220,7 +262,7 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
         ? (parsed as any).total_matching ?? (parsed as any).total ?? null
         : null;
       try {
-        const out = await dispatchToChatSummary(chatParams, newItems, job.id, { totalMatching });
+        const out = await dispatchToChatSummary(chatParams, newItems, job.id, { totalMatching, skills: job.skills });
         recordDispatch({
           job_run_id: runId,
           item_key: `summary-${runId}`,
@@ -262,10 +304,28 @@ export async function executeRun(job: Job, runId: string): Promise<void> {
       const preview = renderItemPreview(item);
       logLine('info', `[${idx}] ${key} — new — dispatching ${job.dispatch_type}…`);
       const dispatchStart = Date.now();
+      // Auto-install any skill named on the job into the dispatch
+      // target project, so the spawned task can actually invoke them.
+      // Skipped for chat dispatches — chat backend already sees globally-
+      // installed skills and we don't have a target project here.
+      if (job.skills && job.skills.length && job.dispatch_type === 'pipeline') {
+        const targetProject = (job.dispatch_params as PipelineDispatchParams).project_path;
+        if (targetProject) {
+          for (const skillName of job.skills) {
+            try {
+              const { ensureInstalledInProject } = require('../skills');
+              const r = await ensureInstalledInProject(skillName, targetProject);
+              if (!r.installed) logLine('warn', `skill "${skillName}" not installable: ${r.reason}`);
+            } catch (err) {
+              logLine('warn', `skill "${skillName}" install failed: ${(err as Error).message}`);
+            }
+          }
+        }
+      }
       try {
         const out = job.dispatch_type === 'pipeline'
-          ? dispatchToPipeline(job.dispatch_params as PipelineDispatchParams, item, key)
-          : await dispatchToChat(job.dispatch_params as ChatDispatchParams, item, job.id);
+          ? dispatchToPipeline(job.dispatch_params as PipelineDispatchParams, item, key, { skills: job.skills })
+          : await dispatchToChat(job.dispatch_params as ChatDispatchParams, item, job.id, { skills: job.skills });
         recordDispatch({
           job_run_id: runId, item_key: key, item_preview: preview,
           dispatch_type: job.dispatch_type, dispatch_target_id: out.target_id, status: 'dispatched',

package/lib/jobs/store.ts

@@ -31,6 +31,15 @@ export function ensureSchema(): void {
       dedup_field                 TEXT NOT NULL,
       dispatch_type               TEXT NOT NULL,
       dispatch_params             TEXT NOT NULL DEFAULT '{}',
+      /** JSON array of skill names (from forge-skills registry).
+          Composed into the task system prompt at dispatch time. */
+      skills                      TEXT NOT NULL DEFAULT '[]',
+      /** 'period' (default — fire every schedule_interval_minutes),
+          'once' (fire once at schedule_at, then auto-disable), or
+          'cron' (fire on each cron tick per schedule_cron). */
+      schedule_kind               TEXT NOT NULL DEFAULT 'period',
+      schedule_at                 TEXT,
+      schedule_cron               TEXT,
       last_run_at                 TEXT,
       next_run_at                 TEXT,
       created_at                  TEXT NOT NULL DEFAULT (datetime('now')),
@@ -74,6 +83,11 @@ export function ensureSchema(): void {
   // Migrations for already-existing job_runs tables.
   try { db().exec(`ALTER TABLE job_runs ADD COLUMN notes TEXT`); } catch {}
   try { db().exec(`ALTER TABLE job_runs ADD COLUMN log TEXT`); } catch {}
+  // Migration for already-existing jobs table.
+  try { db().exec(`ALTER TABLE jobs ADD COLUMN skills TEXT NOT NULL DEFAULT '[]'`); } catch {}
+  try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_kind TEXT NOT NULL DEFAULT 'period'`); } catch {}
+  try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_at TEXT`); } catch {}
+  try { db().exec(`ALTER TABLE jobs ADD COLUMN schedule_cron TEXT`); } catch {}
   ensured = true;
 }
 
@@ -92,6 +106,10 @@ function rowToJob(r: any): Job {
     dedup_field: r.dedup_field,
     dispatch_type: r.dispatch_type,
     dispatch_params: safeParse(r.dispatch_params, {}) as DispatchParams,
+    skills: safeParse(r.skills, []) as string[],
+    schedule_kind: (r.schedule_kind as 'period' | 'once' | 'cron' | 'manual') || 'period',
+    schedule_at: toIsoUTC(r.schedule_at),
+    schedule_cron: r.schedule_cron || null,
     last_run_at: toIsoUTC(r.last_run_at),
     next_run_at: toIsoUTC(r.next_run_at),
     created_at: toIsoUTC(r.created_at) || r.created_at,
@@ -156,8 +174,9 @@ export function createJob(input: CreateJobInput): Job {
     INSERT INTO jobs (id, name, enabled, schedule_interval_minutes,
       source_connector, source_tool, source_input,
       items_path, dedup_field,
-      dispatch_type, dispatch_params)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      dispatch_type, dispatch_params, skills,
+      schedule_kind, schedule_at, schedule_cron)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     input.name,
@@ -170,6 +189,10 @@ export function createJob(input: CreateJobInput): Job {
     input.dedup_field,
     input.dispatch_type,
     JSON.stringify(input.dispatch_params),
+    JSON.stringify(Array.isArray(input.skills) ? input.skills : []),
+    input.schedule_kind || 'period',
+    input.schedule_at || null,
+    input.schedule_cron || null,
   );
 
   // Backfill guard: if mark_existing_as_seen is true (default), we don't pre-seed
@@ -182,6 +205,21 @@ export function createJob(input: CreateJobInput): Job {
     db().prepare('UPDATE jobs SET source_input = ? WHERE id = ?').run(JSON.stringify(inputWithFlag), id);
   }
 
+  // Seed next_run_at so the scheduler picks the job up at the right
+  // moment instead of immediately (which getDueJobs would otherwise
+  // do for any NULL next_run_at).
+  if (input.schedule_kind === 'once' && input.schedule_at) {
+    const t = new Date(input.schedule_at);
+    if (!Number.isNaN(t.getTime())) setNextRunAt(id, t.toISOString().replace('T', ' ').slice(0, 19));
+  } else if (input.schedule_kind === 'cron' && input.schedule_cron) {
+    try {
+      const { CronExpressionParser } = require('cron-parser');
+      const iter = CronExpressionParser.parse(input.schedule_cron, { currentDate: new Date() });
+      const next = iter.next().toDate();
+      setNextRunAt(id, next.toISOString().replace('T', ' ').slice(0, 19));
+    } catch {}
+  }
+
   return getJob(id)!;
 }
 
@@ -190,6 +228,10 @@ export function updateJob(id: string, patch: Partial<{
   source_connector: string; source_tool: string; source_input: Record<string, unknown>;
   items_path: string; dedup_field: string;
   dispatch_type: 'pipeline' | 'chat'; dispatch_params: DispatchParams;
+  skills: string[];
+  schedule_kind: 'period' | 'once' | 'cron' | 'manual';
+  schedule_at: string | null;
+  schedule_cron: string | null;
 }>): boolean {
   ensureSchema();
   const sets: string[] = []; const vals: any[] = [];
@@ -203,6 +245,10 @@ export function updateJob(id: string, patch: Partial<{
   if (patch.dedup_field !== undefined) { sets.push('dedup_field = ?'); vals.push(patch.dedup_field); }
   if (patch.dispatch_type !== undefined) { sets.push('dispatch_type = ?'); vals.push(patch.dispatch_type); }
   if (patch.dispatch_params !== undefined) { sets.push('dispatch_params = ?'); vals.push(JSON.stringify(patch.dispatch_params)); }
+  if (patch.skills !== undefined) { sets.push('skills = ?'); vals.push(JSON.stringify(Array.isArray(patch.skills) ? patch.skills : [])); }
+  if (patch.schedule_kind !== undefined) { sets.push('schedule_kind = ?'); vals.push(patch.schedule_kind); }
+  if (patch.schedule_at !== undefined) { sets.push('schedule_at = ?'); vals.push(patch.schedule_at); }
+  if (patch.schedule_cron !== undefined) { sets.push('schedule_cron = ?'); vals.push(patch.schedule_cron); }
   if (sets.length === 0) return false;
   sets.push("updated_at = datetime('now')");
   vals.push(id);
@@ -224,9 +270,12 @@ export function setNextRunAt(id: string, nextRunAt: string | null): void {
 /** Jobs due to run: enabled AND (next_run_at IS NULL OR next_run_at <= now). */
 export function getDueJobs(): Job[] {
   ensureSchema();
+  // Exclude schedule_kind='manual' — those only run when explicitly
+  // fired via /api/jobs/[id]/fire, never on the scheduler tick.
   const rows = db().prepare(`
     SELECT * FROM jobs
     WHERE enabled = 1
+      AND schedule_kind != 'manual'
       AND (next_run_at IS NULL OR next_run_at <= datetime('now'))
     ORDER BY (next_run_at IS NULL) DESC, next_run_at ASC
   `).all() as any[];