ShipMyAgent
Core Concepts

Service vs Extension

Dedicated guide to responsibility boundaries, call direction, scope, and sharing model

Service vs Extension

This page is a dedicated explanation of how service and extension differ.

One-line Summary (Essence)

  • service: an agent-layer mechanism that must run with concrete context (conversation/model/persistence).
  • extension: a console/platform-layer mechanism whose core is not conversation-context orchestration; it is invoked by services or CLI.

Comparison

Dimensionserviceextension
Primary roleAgent execution mechanism (context-oriented)Console/platform extension mechanism
command/actionRegistered and orchestrated by agent runtimeRegistered and invoked by service/CLI
Typical call directionagent -> serviceservice -> extension, CLI -> extension
Config scopeship.json.services.* (per-project)ship.json.extensions.* (per-project enablement/state)
Context dependencyStrong (ContextManager/model/persistor)Weak or none as core design goal
Asset sharingMostly project runtime state (.ship/*)Often global reusable assets (voice defaults to ~/.ship/models/voice)

Direct Confirmation

  1. service is an agent-layer mechanism and must be combined with concrete context.
  • Confirmed: yes.
  1. extension is context-independent in essence and belongs to console/platform-level extension.
  • Confirmed: directionally yes.
  • Note: extension still receives runtime input, but its core role is not conversation-context orchestration.
  1. service and extension should be documented as two different mechanisms, not one generic “capabilities” bucket.
  • Confirmed: yes.
  1. Voice extension assets are globally shared by default.
  • Confirmed: yes (by default).
  • Note:
    • voice model directory defaults to ~/.ship/models/voice, so multiple agents can reuse downloaded models.
    • each agent still has its own extension switches/config under ship.json.extensions.*.
    • if modelsDir is set to a project path, sharing can be disabled intentionally.

Call Graph

Practical Rules

  • Put context-bound orchestration logic in service.
  • Put platform-level reusable logic in extension.

Architecture Logic Map

Concepts page 2 explaining responsibilities and interaction of console, agent, service, and extension

Invocation Routing and Isolation

Explain why service/extension calls do not cross agent environments and how env-based routing works in shell scenarios