Extension model

Understand Jingle extension packages, manifests, command modes, settings, runtime code, and agent capabilities.

An extension package is the development and distribution boundary in Jingle. A package can declare commands, render React views, define connected accounts, provide a main service, and register capabilities that agents can call.

Package layout

extensions/github/
  manifest.ts
  runtime.ts
  runtime-metadata.ts
  main.ts
  assets/
    icon.svg
  src/
    my-issues.tsx
    create-issue.tsx
    tools.ts
    contracts.ts

File	Responsibility	Status
`manifest.ts`	Title, icon, commands, settings, connection, and AI capability	Preview
`runtime.ts`	View, no-view, and menu-bar command entries	Preview
`runtime-metadata.ts`	Static runtime metadata such as viewport	Preview
`main.ts`	Privileged RPC, tool definitions, local APIs, and provider calls	Preview
`assets/`	Icons and local resources	Preview

Reference visual for an extension command in root search — A package can make multiple commands discoverable from the launcher; each command then chooses whether it renders a list, form, detail view, or no-view action.

Manifest

The manifest is how Jingle identifies an extension. It describes identity, commands, settings, and capabilities through a TypeScript definition:

import { defineNativeExtensionManifest } from "@openwork/extension-api"

export const githubManifest = defineNativeExtensionManifest({
  name: "github",
  title: "GitHub",
  iconName: "github",
  capabilities: ["navigation", "rpc", "surface"],
  commands: [
    {
      name: "my-issues",
      title: "My Issues",
      description: "List GitHub issues created by you, assigned to you, or mentioning you.",
      mode: "view"
    }
  ]
})

Core fields include:

Field	Meaning
`name` / `title` / `description` / `icon` / `iconName`	Extension identity and presentation
`commands`	Commands exposed to the launcher
`preferences`	Extension-level settings
`connection`	Connected-account declaration
`aiCapability`	Agent-visible capability and tool list
`runtimeCapabilities`	Host capabilities the runtime can request
`runtimeShell.allowedUrlSchemes`	URL schemes the command may open
`supportedPlatforms`	Platform constraints

Command modes

mode	Use case	Status
`view`	Commands with a main UI such as search pages, forms, or lists	Preview
`no-view`	Immediate actions without showing a main view	Preview
`menu-bar`	Menu bar status and actions	Preview
`background`	Scheduled or resident background tasks	Planned

Preferences

Extensions and commands can contribute settings. Runtime code reads them with getPreferenceValues().

const preferences = getPreferenceValues<{
  accessToken: string
  apiBaseUrl: string
}>()

type	Value	Status
`text` / `textfield`	`string`	Preview
`password`	`string`, treated as a secret by the host	Preview
`checkbox`	`boolean`	Preview
`dropdown`	`string`	Preview
`appPicker`	application name, bundle id, or path	Preview
`file` / `directory`	file or directory path	Planned

Runtime

Runtime packages use React components to describe command UI:

import { Action, ActionPanel, List } from "@openwork/extension-api"

export default function SearchPage() {
  return (
    <List searchBarPlaceholder="Search workspace">
      <List.Item
        title="Project Plan"
        subtitle="Notion"
        actions={
          <ActionPanel>
            <Action.OpenInBrowser url="https://example.com" title="Open" />
          </ActionPanel>
        }
      />
    </List>
  )
}

The runtime SDK covers lists, details, forms, ActionPanel, MenuBarExtra, toast, clipboard, storage, preferences, navigation, and command handoff. See API reference for the full surface.

Main service

Main service owns privileged or host-side work: provider API calls, filesystem bridges, native capabilities, and agent tool execution. Runtime code should request those capabilities through a service or host capability rather than reading renderer state or local credentials directly.

export const main = defineNativeExtensionMain({
  service: defineNativeExtensionService({
    methods: ["searchIssues"],
    async invoke(request, context) {
      // context.connection / context.extensionPreferences are resolved by Jingle.
    }
  })
})

AI capability

Extensions can declare agent-visible capabilities:

aiCapability: {
  id: "github",
  title: "GitHub",
  requiredPreferenceNames: ["accessToken"],
  publicPreferenceNames: ["apiBaseUrl"],
  toolNames: ["searchIssues", "createIssue"],
  guide: "Use GitHub only after the user connects GitHub."
}

Agents can see capability guidance, tool names, connection status, and presentation metadata. Credentials should not enter the prompt.