@omnitype-code/adapter-sdk

The adapter layer for OmniType v2 deterministic attribution.

This SDK is for AI tool authors and open-source contributors who want to add OmniType attribution support to a coding tool (Cursor, Windsurf, Cline, a custom CLI, etc.).

If you are an AI tool end user looking to track attribution in your own workflow, install the VSCode extension instead.

How the tier system works

Every file edit tracked by OmniType gets an attribution tier:

| Tier | Name | How it's produced | Confidence | |---|---|---|---| | T0 | Deterministic | AI tool embeds @omnitype-code/agent-sdk directly | 100% | | T1 | Hook-inferred | preToolUse hook fires before each tool call | 85% | | T2 | Retrospective | Transcript scavenger reads session logs after the fact | 60% | | T3 | Filesystem-only | File watcher sees a change with no session context | 30% |

The goal is to get as much attribution as possible at T0 or T1. T3 spans have origin='unknown' — they are never assumed to be AI.

Option A — Embed the Agent SDK (T0 path)

Use @omnitype-code/agent-sdk if your tool writes files directly (not via shell hooks).

npm install @omnitype-code/agent-sdk

import { OmniTypeAgent } from '@omnitype-code/agent-sdk';

// On session start (once per AI conversation)
const agent = await OmniTypeAgent.tryConnect({
  workspace: '/path/to/git/repo',
  sessionId: crypto.randomUUID(),
  model: 'claude-sonnet-4-6',
  tool: 'my-tool',
});

// Wrap every file write — produces T0 (deterministic) attribution
if (agent) {
  await agent.withEdit('src/foo.ts', newContent, async (absPath, content) => {
    await fs.writeFile(absPath, content, 'utf-8');
  });
} else {
  // Daemon not running — write normally, attribution will be T3
  await fs.writeFile(absPath, newContent, 'utf-8');
}

// On session end
await agent?.end('tool-exit');

tryConnect returns null if the daemon isn't running — your tool continues working normally and writes are tracked at T3 by the filesystem watcher.

Fine-grained API

// Manual txn control (for multi-file edits)
const txn = await agent.beginTxn(['src/a.ts', 'src/b.ts']);
await writeA();
await writeB();
await agent.commitTxn(txn, [
  { path: 'src/a.ts', preHash, postHash, splices },
  { path: 'src/b.ts', preHash, postHash, splices },
]);

// Emit the prompt (privacy-safe — only hash stored by default)
await agent.emitPrompt(promptText, /* shareText= */ false);

Option B — Write a Manifest (T1 path)

If your tool runs shell commands that can be intercepted via hooks, write a 30-line JSON manifest.

Create .omnitype/adapters/my-tool/manifest.json:

{
  "id": "my-tool",
  "version": "1.0.0",
  "display_name": "My AI Tool",
  "tool_binary": "my-tool",
  "trust": { "trust_circle": 2 },
  "declared_capabilities": [
    "tool.identity",
    "session.id",
    "hook.preToolUse",
    "operation.editOp.path_only"
  ],
  "hooks": {
    "preToolUse": {
      "install_path": "~/.config/my-tool/hooks/preToolUse.sh",
      "one_liner": "echo '{\"type\":\"hook\",\"tool\":\"my-tool\",\"session\":\"$SESSION_ID\",\"file\":\"$FILE\"}' >> ${OMNITYPE_HOOKS_DIR}/event-$(date +%s%N).json"
    }
  },
  "normalize": [
    {
      "match": { "tool_name": "write_file" },
      "emit": "EditOp",
      "path_from": "$.arguments.path",
      "origin": "ai"
    }
  ]
}

Then run:

omnitype-daemon install-hooks

The daemon will install the hook and start receiving T1 events from your tool.

Trust circles

| Circle | Level | Who uses it | |---|---|---| | 1 | Verified partner | Claude Code, Cursor, Windsurf (manifests maintained by OmniType) | | 2 | Community verified | Cline, Copilot (community-maintained, OmniType-reviewed) | | 3 | Community | Unreviewed third-party manifests |

T0 is only achievable via the Agent SDK. Community (circle 3) adapters are capped at T1.

The attribution guarantee

OmniType v2 never assumes an unknown write is AI-generated.

• origin='unknown' means: a file changed, but we don't know who wrote it.
• origin='ai' requires positive evidence: an active AI session txn, a signed Agent SDK event, or a hook payload.
• This is enforced in the SQLite materializer — there is no code path that promotes 'unknown' to 'ai'.

Verifying your adapter

# Check your adapter is installed and recognised
omnitype-daemon doctor

# See live attribution as you code
omnitype-daemon blame src/foo.ts

# Check tier breakdown for the workspace
omnitype-daemon health

Filing issues

Open an issue at github.com/omnitype-code/omnitype-v2 with the label adapter.

Include the output of omnitype-daemon doctor and omnitype-daemon health --json.