Remote exc type registry

[goodboy]

Add reg_err_types() for custom remote exc registry

Summary

• f3726cf9 Add reg_err_types() public
  API in _exceptions enabling user-app code to
  register custom Exception types for cross-actor
  IPC relay and re-raise.
• 1dc45e7a Fix crash when an unregistered
  remote error type is relayed — .src_type and
  unpack_error() now log a warning and degrade
  gracefully instead of raising TypeError.
• e4bdf7ca .boxed_type_str falls back
  to the IPC-msg-encoded type-name string when the
  type object can't be resolved locally; returns
  '<unknown>' when no IPC msg exists.
• 1dc45e7a .unwrap_remoteactor_err()
  falls back to RuntimeError wrapping the original
  traceback when src_type is unresolvable.
• 39b4f083 Add get_runtime_vars()
  copy-accessor to _state.
• af5fcacf c1743fab Add
  comprehensive tests.test_reg_err_types covering
  unit-level reg_err_types() / get_err_type()
  plumbing, IPC-level registered custom error
  round-trips, and unregistered error relay with
  string-level info preservation.
• f6620390 Add /pr-msg skill for
  cross-service PR/patch-request description
  generation.

Motivation

Previously, if a remote actor raised a custom
Exception subclass unknown to the receiving side,
tractor would crash internally (in .src_type or
unpack_error()) with an opaque TypeError. This
made it impossible for downstream libs/apps to
define and relay their own error hierarchies across
IPC without monkey-patching tractor._exceptions.

reg_err_types() provides a clean registration
hook, and the graceful-fallback path ensures even
unregistered types don't break the error relay
pipeline.

Scopes changed

• f3726cf9
  tractor._exceptions.reg_err_types() — new
  public API for custom remote error type
  registration.
  • 1dc45e7a e4bdf7ca Also
    adjusts .RemoteActorError.src_type,
    .boxed_type_str,
    .unwrap_remoteactor_err() and
    unpack_error() in that module for graceful
    fallback.
• 39b4f083
  tractor._state.get_runtime_vars() — new
  copy-accessor for the actor's runtime variables
  dict.
• af5fcacf c1743fab
  tests.test_reg_err_types — new test module:
  unit plumbing + IPC integration (335 lines).
• f6620390 .claude.skills.pr-msg —
  new /pr-msg skill with SKILL.md and
  format-reference.md.

(this pr content was generated in some part by
claude-code)

[Copilot]

Pull request overview

Adds a public registration hook for custom remote exception types so cross-actor IPC error relay can reconstruct and re-raise app-defined exceptions, while also making unregistered/unknown remote error types degrade gracefully instead of crashing.

Changes:

• Add tractor._exceptions.reg_err_types() to register custom exception classes for local type-name lookup during error unboxing.
• Make remote error unboxing more resilient when a type can’t be resolved locally (src_type, boxed_type_str, unwrap(), unpack_error() warnings/fallbacks).
• Add _state.get_runtime_vars() and a new test suite covering registration plumbing + IPC round-trips.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
tractor/_exceptions.py	Introduces custom exception type registry and adjusts RemoteActorError/unpack behavior for unknown types.
tractor/_state.py	Adds get_runtime_vars() copy accessor for actor runtime variables.
tests/test_reg_err_types.py	Adds unit + IPC integration tests for registered/unregistered remote exception relaying.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

get_err_type() is documented/used as returning an exception type, but the annotation is BaseException|None (instance type). This leaks into the new API surface (and unpack_error() typing) and makes it easy to misuse. Update the return annotation to Type[BaseException] | None (or type[BaseException] | None on 3.11+) to match actual behavior.

Suggested change

	def get_err_type(type_name: str) -> BaseException|None:
	def get_err_type(type_name: str) -> Type[BaseException] | None:

[Copilot]

RemoteActorError.src_type uses None both as “not computed yet” and “unresolvable”, so when the type can’t be resolved it will re-run get_err_type() and re-log the warning on every access. Consider using a sentinel value (or a separate boolean) to cache the “unresolvable” state, and also handle self._ipc_msg is None to avoid AttributeError for manually-constructed RemoteActorErrors.

[Copilot]

Spelling in comment: ExceptionGroup.exeptions should be ExceptionGroup.exceptions.

Suggested change

	# `ExceptionGroup.exeptions: list[BaseException]`
	# `ExceptionGroup.exceptions: list[BaseException]`

[Copilot]

These tests mutate global process state by registering CustomAppError / AnotherAppError into tractor._exceptions and never cleaning it up. That makes the unit tests order-dependent and can leak registrations into unrelated tests in the same session. Consider using monkeypatch (or a fixture/finalizer) to remove the injected attributes after each test, or use unique per-test type names to avoid cross-test contamination.

[Copilot]

reg_err_types() docstring has a typo: “recevier side” -> “receiver side”.

Suggested change

	remotely; enables them being re-raised on the recevier side of
	remotely; enables them being re-raised on the receiver side of

[Copilot]

reg_err_types() mutates tractor._exceptions via setattr without validating inputs or guarding name collisions. As written, passing a non-exception (or an exception whose __name__ collides with an existing Tractor exception like RemoteActorError/ContextCancelled) can silently overwrite core types and break get_err_type() lookups. Consider validating isinstance(exc_type, type) + issubclass(exc_type, BaseException) and rejecting/raising on collisions unless the existing attribute is the same object.

Suggested change

	log.debug(
	f'Register custom exception,\n'
	f'{exc_type!r}\n'
	)
	setattr(
	_this_mod,
	exc_type.__name__,
	# Validate that we only register proper exception types.
	if not isinstance(exc_type, type) or not issubclass(
	exc_type,
	BaseException,
	):
	raise TypeError(
	f'Invalid exception type for registration: {exc_type!r} '
	f'(expected an exception class)'
	)
	name = exc_type.__name__
	existing = getattr(_this_mod, name, None)
	if existing is not None:
	# Idempotent re-registration of the same type is allowed.
	if existing is exc_type:
	log.debug(
	'Exception %r already registered; skipping re-registration',
	name,
	)
	continue
	# Prevent silent overwriting of existing exception types or other
	# attributes in this module.
	raise ValueError(
	'Cannot register exception type {!r}: name collides with '
	'existing attribute {!r} on tractor._exceptions'.format(
	exc_type,
	existing,
	)
	)
	log.debug(
	f'Register custom exception,\n'
	f'{exc_type!r}\n'
	)
	setattr(
	_this_mod,
	name,