@copado/agentia-plugin-sdk

Base command and host lookup for Agentia CLI plugins. The package contains no authentication or credential code. At runtime the Agentia CLI registers a host object, and plugins call a small set of domain methods on it.

Usage

import {AgentiaCommand, getAgentiaHost} from '@copado/agentia-plugin-sdk'

export default class HealthCheck extends AgentiaCommand {
  public async run() {
    const host = getAgentiaHost()
    const report = await host.organization.healthCheck()
    this.display(() => {
      this.log(host.format.table([{field: 'name', header: 'Check'}, {field: 'status', header: 'Status'}], [...report.checks]))
    })
    return report
  }
}

Declare the host methods your plugin needs. An older CLI that lacks one fails with a clear "update the CLI" message instead of an undefined is not a function:

const host = getAgentiaHost({requires: ['organization.healthCheck', 'format.table']})

The requires paths are type-checked against the host API.

Host API

Methods describe intent (get a work item, check organization health), not Copado endpoints or CLI commands. Results are plain, read-only shapes defined by this package, and every result and error is redacted before the plugin sees it.

| API | Purpose | | --- | --- | | host.work.getWorkItem(id?) | Get a work item by Id or name, or the active work item when id is omitted | | host.work.list(query?) | One page of work items, same fields as getWorkItem | | host.user.get(id?) | The signed-in user (id, fullName, username), or a user by Salesforce Id | | host.workspace.current() | Active story, base branch, git branch, and non-secret project defaults. No pull-request URLs or credentials | | host.project.current() | The project selected by those defaults | | host.project.list(query?) / host.project.get(id) | Project id, name, status, dates, description, owner, and pipeline id and name | | host.project.defaults() | Effective project defaults. credential is an id or name. A local value overrides a global one | | host.pipeline.list(query?) / host.pipeline.get(id) | Pipeline identity, connections (branch and environment id and name), and stage connections | | host.stage.list(query?) | Stage id, name, and meta stage | | host.environment.list(query?) / host.environment.get(id) | Environment id, name, type, platform, org id, namespace, and last refresh date | | host.promotion.list(query?) / host.promotion.get(id) | Promotion summary: status, environment, pipeline, and project names, dates | | host.job.list(query?) / host.job.get(id) | Job status, template name, and step name, type, and status | | host.organization.healthCheck() | Run the organization governance health check and get a normalized report | | host.auth.status() | Which of cicd, crt, and ai are configured (configured, ready, source only). ready for AI means a call can run, including env-var keys, and still returns no key | | host.ai.ask({prompt, agent?}) | One tool-less prompt to a named agent (orchestrate by default, which routes to a specialist: orchestrate, plan, build, test, release, operate, knowledge). There is no model argument and no streaming. The call spends AI quota | | host.ai.quota() | AI quota usage and limit, the same numbers as ai quota get | | host.format.table(columns, rows) | Render a terminal table, using the same formatting as built-in commands |

List queries accept an optional name and pageSize (1–200). Stage list accepts pageSize only. Each call returns one page.

There is no way to call arbitrary endpoints. If you need a capability that is not listed, request it from the Agentia CLI team; each method is a deliberate, reviewed addition.

Do and don't

• Do extend AgentiaCommand from this package. It provides --json output, display, and withSpinner.
• Do rely only on the fields declared in index.d.ts.
• Don't import @copado/agentia-cli or its internals; they are not a supported dependency.
• Don't expect API keys or any other credential from the host.
• Don't pass a model name to ai.ask. Copado selects the model for the named agent.
• Don't run agentia as a subprocess or instantiate oclif Command classes from the CLI as a library.

Contribute agent skills

A plugin can offer agent skills to agentia setup skills by exporting an agentia:contribute oclif hook that returns defineContributions(...). The CLI runs the hook of each installed plugin once, with a 5 second timeout, only when the user asks for plugin skills (interactive setup skills create, --plugin, setup skills list, or setup skills update when plugin skills are already installed). It never runs for plain core-only runs.

{
  "files": ["dist", "skills"],
  "oclif": {"hooks": {"agentia:contribute": "./dist/hooks/contribute"}}
}

import {defineContributions} from '@copado/agentia-plugin-sdk'

export default async function () {
  return defineContributions({
    apiVersion: 1,
    skills: [
      {
        id: 'release',
        files: [{path: 'skills/agentia-release/SKILL.md'}, {path: 'skills/agentia-release/references/notes.md'}],
      },
    ],
  })
}

• apiVersion is SUPPORTED_CONTRIBUTION_API_VERSION (currently 1), separate from the host API version. A CLI that does not support your version skips the contribution with a message.
• id is lowercase letters, digits, and single hyphens (max 56). The CLI installs the skill as agentia-<id>, so the name in the SKILL.md frontmatter must be agentia-<id>. agentia, cicd, testing, ai, and adv are reserved, and an id another installed plugin also contributes is rejected for both. description is 1-1024 characters.
• files are paths relative to your plugin root. Exactly one is a SKILL.md; its directory is the skill directory and every other file lives below it. Add the directory to files in package.json or the published package leaves it out.
• Markdown only, at most 50 files, 256 KiB per file, and 1 MiB per skill. No scripts, symbolic links, hidden files, absolute paths, .., or allowed-tools.
• A rejected skill is skipped with a reason (see agentia setup skills list); your other skills and other plugins still install. A hook that throws or times out only skips that plugin.
• mcpTools is typed for a later release. This CLI ignores it.
• The hook receives the oclif config and no credentials; it is a way to name files, not to run code for users. Users opt in per plugin skill (interactive tick, none preselected, or --plugin <your-package>), and agentia setup skills update refreshes what they installed. When your plugin is uninstalled or stops contributing a skill, users clean up with agentia setup skills update --prune.

Trust model

Plugins run in the same Node process as the CLI, with the user's permissions. The host API never hands a plugin a credential, but it cannot stop a malicious plugin from reading process.env or the OS keychain itself. Install only plugins you trust.

The agentia:contribute hook is plugin code running in that same process, so it has the same trust level. The CLI limits what it does with the result, not what the hook can do: it validates every returned contribution, installs only Markdown files from inside the plugin directory, and writes them only after the user opts in.

Compatibility

getAgentiaHost() throws when the plugin runs outside the Agentia CLI, when the CLI provides a different host API version than SUPPORTED_HOST_API_VERSION, or when a method listed in requires is missing.

Adding a method or an optional result field is not breaking: it ships as a compatible SDK release, and plugins that use it list it in requires. Renaming or removing a method, or removing a result field, is breaking and increments both the host API version and the SDK's breaking-release version. Before 1.0.0, that means the next minor version under npm SemVer; after 1.0.0, it means the next major version. A breaking change is described in this README and the CLI changelog before that SDK version is published.

Contributions (defineContributions) use SUPPORTED_CONTRIBUTION_API_VERSION, versioned separately from the host API. Adding an optional field is compatible. Renaming or removing a field bumps that number, and an older CLI skips that plugin's contribution with a message while core skills and other plugins keep working.